Troubleshooting

A story doesn’t show up or can’t launch

Check the story’s frontmatter for these three things.

It needs source_repo. A story with no source_repo can’t launch until it names its repo. Add the repo it belongs to:

---
type: story
story_id: LL-231
title: Cart summary tax breakdown
status: review
source_repo: ledgerline/web
---

Without it, the story is left out of the story index: it can’t be opened as a workspace, and other stories can’t find it by id.

It needs an explicit type. Use type: story, type: bug or type: spike. Any other value makes the file a plain doc. Always write the type out.

Quote values that contain : . A value such as title: Checkout: tax lines breaks the YAML, and the story silently drops out. Write title: "Checkout: tax lines".

For an HTML story, the same fields go in meta tags: cs:story-id, cs:source-repo, cs:depends-on and so on. See Story and epic fields.

Let your agent check it

Ask an agent launched from CodeSense to run validate_story on the file. It reports MISSING_SOURCE_REPO, UNKNOWN_SOURCE_REPO, INVALID_TYPE, INVALID_STATUS, DUPLICATE_STORY_ID, UNRESOLVABLE_DEPENDS_ON and UNPARSEABLE_FRONTMATTER.

Coming

Work-item types beyond story, bug and spike, set per team.

Unlocks with configurable work-item types.

A page action says denied: write budget

A runaway guard stopped the page after a large batch or a burst of writes in one render. Reload the page to reset it. If an agent wrote the page, ask it to batch fewer writes per click.

“No local clone attached”

This appears when a story’s repo is tracked in your workspace, but CodeSense doesn’t know where its clone lives on this machine. Choose Attach local clone, then either Browse for clone directory to pick an existing checkout, or Clone for me. Worktrees, terminals and editor actions for that repo work once it’s attached. See Attach your repos.

The agent’s first command ran before the context landed

When a worktree opens, the terminal is ready as soon as git worktree add finishes. Your team’s context (.claude/, CLAUDE.md, skills) is written a moment later. If you type a command immediately, it can run before those files exist. Wait a few seconds, or re-run the command. Later commands see everything.

Coming

A terminal that shows when context is still landing, or holds the first prompt until it has.

Unlocks with a context-landing indicator.

An agent says “CodeSense is not running”

The agent’s MCP bridge couldn’t reach the app. Open CodeSense. The bridge reconnects on its own for about 30 seconds after the app restarts. After that, restart the agent session.

Claude Code or Codex isn’t offered

CodeSense looks for claude and codex on your login shell’s PATH and needs claude 2.0 or newer, or codex 0.140 or newer. Install or update the CLI; CodeSense notices new installs. Git 2.44 or newer is the only thing CodeSense requires to start.

My bash or fish config isn’t loaded in the terminal

CodeSense terminals always start a login zsh, which loads your zsh dotfiles. Bash and fish configs aren’t read. See Terminals.