Launch your first agent

Every story gets its own worktree: a separate checkout of its repo, on its own branch, with your team’s context already written in. You open it from the story, and run Claude Code or Codex in its terminal.

This page uses Ledgerline’s story LL-214 (“Refund endpoint idempotency keys”), which changes ledgerline/api.

Before you start

• The story’s repo is attached. See Attach your repos.

• The story file has type: story (or bug or spike) and a source_repo. The first lines of LL-214 look like this:

  ---
  type: story
  story_id: LL-214
  title: Refund endpoint idempotency keys
  status: review
  source_repo: ledgerline/api
  depends_on: [LL-209]
  ---

• claude or codex is installed and on your PATH.

1. Open the story’s worktree

In the left nav, right-click the story and choose Open story workspace.

The first time, CodeSense creates the worktree and its branch, then opens a terminal there. Next time, it reopens the same one.

• Branch. The story’s branch field if it has one; otherwise the repo’s branch prefix plus the story id. With the default prefix feat/, LL-214 gets feat/LL-214.
• Folder. By default ../{repo}-wt/{slug} next to the repo’s clone, where {slug} is the branch with / turned into -. For a clone at ~/code/api, that’s ~/code/api-wt/feat-LL-214.

You can change both per repo. See Worktrees.

2. Check the context is there

The terminal opens as soon as the worktree exists, and the context write follows a moment later:

ls CLAUDE.md AGENTS.md .claude/skills
git status --short    # clean: context paths are excluded from git

3. Start the agent

Type the agent’s command in the terminal, as you would anywhere else:

claude
# or
codex

The agent starts in the worktree, so it reads the team’s CLAUDE.md or AGENTS.md and skills from the folder. CodeSense also registers its MCP bridge in the worktree’s .mcp.json and .codex/config.toml, kept out of git, which gives the agent CodeSense tools such as validating a story or pulling an epic’s stories into the worktree. See MCP tools for agents.

A good first prompt names the story:

Implement story LL-214. Read the story and its depends_on stories first,
and use the add-endpoint skill.

One action instead of three

Right-click the story in the left nav and, under Launch agent, choose your agent. CodeSense opens the worktree and starts the agent there with a prompt to read the story and complete it.

4. Read the status dot

Beta Needs Claude Code's hooks or Codex's notifications

A terminal tab running an agent shows a small dot that tracks it, so you don’t have to watch every terminal. Claude Code reports through a hook; Codex through its notifications. The dot hasn’t been checked end to end with a real Claude Code session yet, so treat the colours as a guide.

Dot	Meaning
Blue, pulsing	Working
Orange	Needs your permission
Amber	Done
Red	Error
Hollow grey ring	Idle

Your settings stay yours

CodeSense writes its status hook into .claude/settings.local.json in the worktree, never into your .claude/settings.json, and excludes it from git. See Keep your own Claude Code hooks.

What’s next

• Launch several stories at once and watch them side by side: Launch agents and watch them.
• Bring your own scripts and CLIs: Run your own tools and scripts in a worktree.
• When the story is merged, CodeSense can remove its worktree for you. See Worktrees.