CmdQ user manual

Header

• 5-hour window and Weekly limit bars show how much of each limit you've used. The ring shows the 5-hour figure.
• Next reset counts down to the next 5-hour reset. Weekly reset does the same for the weekly limit.
• When the weekly limit is used up, the label changes to Weekly limit · resumes and the queue waits for the weekly reset.
• Unreadable means the last usage check failed. N/A means your plan doesn't report that value.
• On the right: N terminals (only while background terminals exist), ☆ Bookmarks, the light/dark toggle, and ⚙ Settings.

Project tabs

Each tab is one project folder. Click + Folder (⌘O) to open one. A tab shows only the items for its path, and the add bar uses that path. Switching tabs resets the add bar to the Path target and the To Do queue.

Closing a tab (⌘W or the tab's ×) deletes nothing. Auto queue items for that path keep running. Drag tabs to reorder them.

Turn on Show all (⇧⌘A) to see items from every open tab, grouped by path. Dragging cards is locked while it's on.

Queues and item numbers

Below the add bar are two lists: Auto queue and To Do. In the auto queue, the circle on the left of a card is its place in line. It turns into a pulsing light while the item runs and a ✓ when it's done. The #12 chip is the item's ID. It never changes, and notifications use it to name the item.

Menu bar icon

CmdQ keeps running in the menu bar after you close the window, and the auto queue keeps going. Choose Quit (⌘Q) in the menu to stop it.

Click the icon for a menu showing your plan, both usage figures, reset countdowns and an auto queue summary. Below that: Refresh usage, Open window, Settings…, Open log folder, About, Check for Updates…, Report a bug, Request a feature and Quit. Report a bug opens a prefilled GitHub issue in your browser with the app version, macOS version and CPU type. Nothing is sent until you submit it.

CmdQ checks for a new version about 20 seconds after launch and every 6 hours after that. When one is available it asks first, and only downloads, installs and restarts when you choose Install and Restart. If auto queue tasks are running or interactive terminals are open, the prompt says they will be stopped by the restart. A version you put off with Later isn't offered again until the app restarts; in the meantime you can install it from Check for Updates…, which also tells you when you're already up to date.

1. Open a project tab with + Folder.
2. Type the prompt or command you'd give claude, for example /code-review or Fix the failing login test.
3. Press a submit key, or click Add to use the queue picked in the add bar.

These keys are fixed. They work the same no matter which queue the add bar shows, and you can't reassign them.

Skill autocomplete

Start a word with / and a list of your skills opens, labeled User, Project or Plugin. ↑ ↓ move the highlight, Tab inserts the skill, Esc closes the list. Enter does not pick a skill. It submits the text exactly as typed.

Images and paths

• Paste an image and it shows up as [IMAGE]. CmdQ saves the image and hands its path to claude when the task runs. Backspace right after the marker deletes it.
• Type @ to browse files and folders under the tab's path (or the session's folder for a session target). Tab or Enter inserts the path.
• Type # to insert attachment markers. See Attachments.

The target decides where a task runs. Pick it with the buttons in the add bar or ⌃1 ⌃2 ⌃3.

Session target

• Click Session, then pick from the session list for the tab's path. Each row shows how much of the context window that session has used. Sessions you started with Interactive carry an Interactive badge.
• 🕐 History lists the questions asked in the selected session.
• ▶ Terminal opens the selected session in an interactive terminal (Interactive terminal).
• A session task waits while that session is in use elsewhere: an interactive terminal in CmdQ, another queue item, or a claude process outside the app. A toast reads Waiting · … with the reason.

Interactive target

The text in the command box becomes your first message. An empty box opens a blank session. It won't open while the add bar holds pending attachments or attachment markers, because markers aren't expanded in an interactive session.

Changing a card's target

The small button next to a card's path or session chip switches the target: Switch to a session on a path card, Switch to a path on a session card. It isn't shown on running or finished items, on chain parents or on chain children.

How many run at once

• Within one path, the auto queue runs one item at a time, top to bottom.
• Different paths run side by side. Auto-queue concurrent runs (default 3) caps how many paths go at once. Runs you start by hand don't count.
• Concurrent runs per path (default 2) caps automatic plus manual runs in one path. At most one of them is automatic. Set it to 1 if your tasks edit files, because two runs touching the same file overwrite each other.
• Session targets also wait while their session is busy.

Moving items

• ▶ Promote to the auto queue on a To Do card moves it to the end of the auto queue. It starts when its turn comes.
• Move to To Do on a waiting or failed auto queue card moves it back.
• Drag a Queued or Waiting for reset card up or down to change the order. Running and finished cards stay put.

Status badges

Hover a Failed or Waiting for reset badge to see the reason. Click it for the full text.

A Running item keeps going as long as claude produces output. After 30 minutes with no output, CmdQ treats it as stuck, stops it and marks it Failed with "Stopped: no output for 30 minutes". Even with steady output, a run that passes 6 hours stops with "Stopped: exceeded the 6-hour maximum run time". Either way the queue moves on to the next item. You can't change these two limits in Settings.

Making a chain

1. Add the parent and the follow-up tasks to the same path, in the order you want them to run.
2. Drag a follow-up card a little to the right while moving it (about 32 px). The drop slot indents.
3. Release. The card becomes a child of the card above it. If the card above is itself a child, the new card joins the same parent as its next sibling.

Rules for nesting:

• Both cards must use the Path target. Session tasks can't be nested; tasks for one session already run in order.
• Chains go one level deep. A card that already has children can't become a child.
• Only Queued or Waiting for reset cards can be dragged. This works in both the auto queue and To Do.
• Dragging is locked while Show all is on. Pick a single tab first.
• Use ▾ / ▸ on the parent to expand or collapse its children.

How a chain runs

Recovering from a failed parent

1. Click Run interactively on the failed parent. Its session opens in an interactive terminal with the earlier conversation.
2. Talk claude through the fix, or send one message such as continue.
3. Your first message marks the parent Done. The child resumes the parent's session, so it waits while a terminal still holds that session. Click Terminate on that terminal, and the first child starts on the next queue check.

Editing a chain

• Detach from the chain (run standalone) on a child turns it into a normal item, placed after the rest of the chain. It stops waiting for the parent.
• Stop (move back to queued) on any running item in a chain moves the whole chain to To Do. Finished steps stay Done. Promote the parent later and the chain picks up at the first unfinished step.
• Move to To Do on a parent, or on a failed child, also moves the whole chain.
• Delete on a parent deletes its children too, and stops any of them that are running.
• Children have no 📎 button. They share the session's attachments, so add them from the parent card's 📎.
• Children have no ▶, ⌘ or ☆ buttons of their own, except that a failed child gets Re-run and Move to To Do.

Example: build, then explain the failure

The child reads the build output already in the session, so you don't need to paste logs into the second prompt.

Example: refactor, test, write the commit message

If /test fails, the commit message step waits. Fix the tests (or re-run the child) and the last step follows.

When a limit is reached

• CmdQ stops every running queue item, not only the one that hit the limit. Each goes to Waiting for reset.
• Interactive terminals are closed (reclaimed). A terminal opened from a card puts its item in Waiting for reset.
• A terminal with no card (opened with Interactive, ▶ Terminal or a bookmark) gets a row in the background terminal list: Waiting for reset · resumes HH:MM. Click the row to read the past conversation. Cancel resume keeps it from reopening.
• You get a Terminal reclaimed notification for each closed terminal, and the menu bar icon gets a yellow dot.
• The auto queue banner shows how long until queued items start again.

After the reset

• Paused items run first, in the same claude session, with this prompt instead of the original command: Continue the work you were doing. Pick up from where it stopped and do not redo what is already finished.
• An item that hit the limit before it had a session reruns its original command.
• Card-less terminals reopen in the background with the same prompt. No window pops up. A toast says how many were resumed. Open them from N terminals.
• After a weekly limit, the queue waits for the weekly reset, not the 5-hour one.

Statusline connection

On first launch CmdQ asks once whether to connect Claude Code usage. Connect points statusLine in ~/.claude/settings.json to a CmdQ wrapper, so usage updates faster and more accurately. Your existing statusline display stays as it is. Later keeps the periodic /usage checks only. Either way, CmdQ doesn't ask again for that Claude config folder, and Settings has no switch for it.

Clicking the card itself

• Click the command text to read the whole command. Esc or a click outside closes it.
• Click a session chip to copy cd '…' && claude --resume …, ready to paste into Terminal.
• Click a path chip to copy the path.

Adding

• In the add bar: File, Link or Memo. They're saved with the new command when you add it.
• On a card: open 📎 and add from the drawer.
• Drag files from Finder onto the add bar or an open drawer.
• Links must start with https:// or http://. Memos are Markdown.
• 📎 in a bookmark row or a terminal works on the same session, even after the card is deleted.

Using them in a command

Attachments reach claude only when the command contains a marker. [첨부] passes every attachment in the session. [첨부:3] passes attachment 3 only. The marker word is Korean in every UI language. Type it as shown.

Type # to pick instead of typing markers. The list has All attachments, Session attachments and Command attachments. Space checks several, Tab or Enter inserts their markers.

Viewing

• Text files and memos open as Markdown or Raw text. Images and PDFs preview in place.
• Web links open inside the app and keep your sign-in. Open in browser and Reload sit in the toolbar.
• For pages behind a sign-in, click Save text. claude then gets the saved copy instead of a URL it can't open. Pages over 1 MB are saved only up to that size.
• Text over 2 MB isn't previewed. Use Show file location and open it in another app.

Limits

Lifetime

CmdQ stores copies. Your original files stay where they are. The copies are deleted once no command, bookmark or open terminal uses the session. When deleting a bookmark would remove them, CmdQ tells you how many and asks first. A resumed run (after a limit, or a reopened session) doesn't get the attachment block again; the session already has it.

Interactive terminals don't expand markers. In a terminal, use 📎 in the header to paste attachments into the input line (Interactive terminal).

Opening one

• Run interactively on a card.
• The Interactive target in the add bar (⌃3). New session, no card.
• Session target, then ▶ Terminal. Reopens that session.
• ▶ on a bookmark, or a row in the background terminal list.

If the session is open in another live terminal, CmdQ reattaches to it instead of starting a second claude.

Taking over a session the queue is running

Opening a session with ▶ Terminal, a bookmark or the terminal list while the auto queue is running it asks first: stop the queue run and hand the session to an interactive terminal? The question also says how many background tasks in that session will be stopped. Confirm, and the run stops, the terminal opens, and the item is marked done with a Handed off badge. Cancel changes nothing. From a card, you get no prompt. CmdQ tells you to open it again after the run finishes.

Header

• Click the project name to copy the project path. Click the session label to copy the claude --resume command.
• Run in background closes the window and leaves claude working. The card shows Terminal running; click it to reattach.
• Terminate stops claude and ends the session.
• ☆ bookmarks the session, even without a card.
• 🕐 opens this session's question history over the terminal. Pick a question to read its reply; close it (×, Esc or a click outside) to return to the same terminal and keep typing. It reloads on every press. It stays disabled until the session id is known.
• 📎 opens the session's attachments. Add, delete, reorder, edit memos or drop files, as in the drawer. Insert into terminal or Insert all pastes them into claude's input line; you press Enter yourself.
• Snippets opens saved commands in two lists, Shared and This path. Pick one to fill the edit box, then Apply to paste and run it. Edits there apply to that run only. ⇧⌘P toggles the panel and jumps to the new-snippet form.

Background terminal list

N terminals in the header (⇧⌘T) lists live terminals and terminals waiting for a reset. Click a row to open it. Each row also has 📎, ☆, ✎ Rename and Terminate. ✎ Rename on a live terminal's row sets the name shown in the list. Press Enter to save or Esc to cancel. The same name appears on the Waiting for reset row and in the terminal window header, but only the ✎ on the list row changes it. Clear the name and confirm to go back to the original title. The name stays after you restart the app. It changes only the displayed title; the queue card's command, the bookmark alias and the path shown stay the same. Terminate all asks for a second click. A terminal opened from the list returns to the list with ⌃←.

While you work

• When output stops for 8 seconds, you get a Waiting for input notification. It isn't sent while you're looking at the window. Change or turn off the delay with Interactive input-wait alert.
• ⌘+click a URL to open it in your browser.
• Mod panels take mouse clicks only with claude's fullscreen renderer: run /tui fullscreen in claude, or start it with CLAUDE_CODE_NO_FLICKER=1. With the default renderer, claude ignores the mouse.
• Emoji count as two cells, as in claude, so tables and panels stay aligned. For a wider terminal, set Terminal window width to Full width.
• When you come back from another app or reopen a terminal, CmdQ has claude redraw the screen. If the screen still goes blank, press ⇧⌘D to save a diagnostics file to diagnostics/ in the app data folder and attach it to a bug report. It contains terminal output, so read it before sharing.
• If a usage limit hits, the terminal closes and resumes after the reset (Usage limits).

• In session history, check questions (or Select all) and save them as 🖼 Image or 📄 PDF.
• On a reply, ⧉ Copy copies it and ← Back (⌃←) returns to the list.
• Run logs are what the response and live log read. Settings controls when they're compressed and deleted. Session history comes from Claude Code's own files, which Claude Code deletes on its own schedule (Troubleshooting).

A bookmark keeps a session after its card is gone, along with the session's attachments.

Adding

• ☆ on a finished auto queue card. Chain children don't have one; they share the parent's session.
• ☆ in the interactive terminal header.
• ☆ on a row in the background terminal list.

The alias is the first line of the command (or of the first prompt for a card-less terminal), cut at 60 characters. With no text, it's the first 8 characters of the session ID. A lit ☆ means the session is already saved; click it again to remove it.

The panel

Open it with ☆ in the header (⇧⌘B). Bookmarks are grouped by path and searchable.

Changing a shortcut

In Settings › Shortcuts, click a key field and press the new combination. Clear sets it to None. Default restores the original.

• A combination needs ⌘, ⌥ or ⌃.
• A combination already in use is refused with the name of the action that has it.
• You can't assign: the app menu keys (⌘C ⌘V ⌘X ⌘A ⌘Z ⇧⌘Z ⌘Q ⌘H ⌥⌘H ⌘M ⌃⌘F), the submit keys (⌘Enter ⌃Enter ⌃⌘Enter), and ⇧⌘D (save terminal diagnostics).

When shortcuts work

• Only while the CmdQ window has focus.
• In a text field, only combinations with ⌘, ⌥ or ⌃ fire.
• With a full-screen view open (terminal, history, settings), only Settings, Add snippet and Back work, plus Terminals to close the terminal list.
• If macOS Mission Control uses ⌃← for "Move left a space", it gets the key first. Assign Back to something else.

Settings live in ~/Library/Application Support/com.doitasap.cmdq/config.toml. A few keys exist only there.

• Quit CmdQ before editing. Saving in Settings rewrites the whole file and drops edits made while the app was running.
• Out-of-range values are clamped to the nearest limit, and CmdQ tells you which ones.
• A file that can't be parsed is moved to config.toml.bak, and CmdQ starts with defaults.

Still stuck? Choose Report a bug in the menu bar menu.