Launch agents and watch them

The left nav shows what’s ready. This guide takes a ready story from the nav, opens its workspace (a worktree in the story’s repo, with your team’s context already in place), starts an agent there, and then keeps an eye on several agents at once.

The example is Ledgerline’s sprint: LL-233 (refund button, in web) and LL-209 (payment intents, in api).

1. Pick a ready story

In the left nav, a not-started story whose dependencies are all done is marked ready. Hover it to check (“Ready — all dependencies met”). Click it to open the story file and read it. See Dependencies and readiness.

To open a story’s workspace and start an agent in one action, right-click it and, under Launch agent, choose your agent. The next two steps do the same by hand.

2. Open the story’s workspace

Use any of these:

• Left nav: right-click the story and choose Open story workspace.
• ⌘K: search for the workspace by name.

CodeSense then:

1. Looks up the story’s source_repo and finds your clone of that repo. If you haven’t attached one, it asks you to (No local clone attached › Attach local clone).
2. Creates a git worktree for the story next to your clone, on its own branch. By default the branch is feat/ plus the story’s file name, and the prefix is configurable per repo. If the worktree already exists, CodeSense reuses it.
3. Copies the context your agent’s definition asks for into the worktree as files, in one batch: by default CLAUDE.md and .claude/ skills, commands, hooks and agents for Claude Code, or AGENTS.md and .agents/skills for Codex, plus the MCP config for CodeSense’s tools. None of it is committed: the paths go in the repo’s git exclude.
4. Opens the workspace with a terminal tab in the worktree.

3. Start your agent

The terminal is your login zsh, with your own dotfiles, already in the worktree. Start your agent there:

claude

Claude Code starts with the team’s context and CodeSense’s MCP tools in place. On a brand-new worktree, the terminal can open a moment before the context has finished landing, so give it a second before your first command. You can run any other CLI the same way, including Codex. See Switch a story between Claude Code and Codex.

Repeat for LL-209. Its workspace opens in your api clone.

Beta Needs a trusted page that declares openWorkspace

A dashboard page can also open a story’s workspace with its agent, using the page SDK’s openWorkspace action. A page button starting an agent hasn’t been recorded in the app yet. See Dashboards and pages.

4. Watch them side by side

Each workspace has its own terminal tabs. New terminal adds another one. To see several at once:

• ⌘⇧L (Cycle Terminal Layout) switches tiles between Columns, Rows and Grid.
• ⌘1 to ⌘9 jump between workspaces, and ⌘0 goes back to the root workspace.
• Each tile’s View options menu can minimize or close it.

Beta Needs Claude Code's hooks

A Claude Code session shows a status dot on its tab and in the workspace tray. The dot is driven by Claude Code’s hooks, so you can see which agent needs you without watching every terminal. It hasn’t been checked end to end with a real Claude Code session yet.

Dot	Meaning
Pulsing blue	Working
Orange	Needs permission: it’s waiting on you
Amber	Finished its turn
Red	Error

5. Follow what an agent is changing

Open a tile’s View options menu and choose Source diff (or press ⌘⇧D). You get a live diff of the worktree against its base. You can view it side by side or inline, and a structural mode compares the code’s syntax instead of lines. Follow edits is on by default, so the view jumps to the newest change as the agent writes it. If you scroll away, ↓ Jump to latest brings you back.

6. The agents list

Sessions that CodeSense launched and manages (from a page, a run, or a headless agent) are listed in the Agents list on the left of the bottom terminal area, grouped by story. Click a row to reveal its tab; right-click it for Reveal, Open story and Stop…. The stop button in the list’s header (Stop all unattended) stops every background session that has no tab.

When an agent finishes, it calls signal_done to record the result. Moving the story on is a plain status edit, by you or the agent. See Statuses and phases.

Note

Other agents you run in a workspace terminal work normally, but their tabs don’t show the status dot.

Coming

A manager agent you choose working through every ready story in a sprint, in dependency order, with one agent each, shown on a recorded, unedited run.

Unlocks with a recorded sprint run.