Agents and runtimes

CodeSense doesn’t ship its own coding agent. It launches the agent CLI you already use, in the story’s worktree, with your team’s context and CodeSense’s MCP tools already in place. Two agents are built in today: Claude Code and OpenAI Codex.

Built-in runtimes

CodeSense drives each CLI through a built-in adapter: which binary to run, which versions it needs, how to wire the CodeSense MCP bridge into its config, and how it signals that it needs you. Adapters are part of the app, not files you edit. You customise a launch through an agent’s agent.yaml: its runtime, args (a --model flag included), MCP servers, permissions and startup files. Which login runs it is your own binding on each Mac, not part of the agent.

	Claude Code	Codex
Binary	claude (2.0 or newer)	codex (0.140 or newer)
MCP bridge written to	.mcp.json	.codex/config.toml
Starter agents	builtin/claude, builtin/claude-unattended	builtin/codex, builtin/codex-unattended
Stripped from the environment	ANTHROPIC_API_KEY	OPENAI_API_KEY

API-key variables are removed from the agent’s environment so it uses the account you signed in with in the CLI. Each CLI still does its own sign-in; CodeSense holds no agent credentials.

CodeSense finds claude and codex on your login shell’s PATH, even when you start the app from Finder. An agent that isn’t installed (or is below the minimum version) is simply unavailable. Git is the only hard requirement.

The config file the bridge goes into is only written inside worktrees and clones CodeSense manages, and it’s added to git’s exclude list so it never shows up in your commits.

Every launch names an agent

An agent is what runs: its runtime (Claude Code or Codex), args, MCP servers, permissions and startup files. Every way of starting a CLI session names one: the story Launch agent menu and the account launch dialog, a dashboard’s openWorkspace (agent), the open_workspace MCP tool, routines and Weft workers. A launch that names none runs builtin/claude; builtin/codex is the other starter. Each has an unattended twin, builtin/claude-unattended (Claude Code with permission checks skipped) and builtin/codex-unattended (Codex with approval never and the danger-full-access sandbox), which runs without asking for permission. A background launch that names no agent (a headless open_workspace, a dashboard’s openWorkspace with headed: false) runs builtin/claude-unattended, and a Weft worker runs the unattended twin of its provider, so a session nobody is watching never waits on a permission prompt. It runs on the account you bound to the ordinary starter unless you bind the twin to its own. An agent on a remote machine always opens as a tab there, so it keeps builtin/claude. A named agent always runs with its own permissions. All starters are read-only; Copy to Mine makes an editable agent from one. Create your own agents in the Agents tab.

An agent runs in one of two execution modes:

• Interactive (the default): the agent runs in a terminal tab in the story’s workspace.
• Headless: there’s no terminal tab. The run is observed in the Agents list in the bottom workspace, where Stop all unattended stops every background agent.

Agents that skip permissions

builtin/claude and builtin/codex use the CLI’s own permission settings. The unattended starters, and any agent whose args carry a bypass flag (such as --dangerously-skip-permissions), act without asking. CodeSense warns about a bypass flag on your own agents and adds one only through the unattended starters.

MCP scope

By default an agent sees every MCP server in the repo’s config. An agent in the Agents tab names the servers it may use; codesense is always on.

At launch, CodeSense writes a temporary, machine-local config that contains only the allowed servers plus the CodeSense bridge, and deletes it when the session ends. Your shared .mcp.json is never changed.

Raw terminal snapshots

An agent’s Your account area in the Agents tab has Retain raw terminal snapshot for completed runs. It’s yours alone, kept on this Mac, and applies only to that agent’s interactive launches.

Agent accounts

If you use more than one Claude or Codex subscription, CodeSense can hold several agent accounts, mark one active, and resolve which one a launch uses. Manage them in the Agent Accounts tab, opened from Connections.

Live status

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

Each agent session shows a status dot: running, done, error or needs permission. Claude Code reports through hooks CodeSense installs; Codex through its notifications. It hasn’t been checked end to end with a real Claude Code session yet. See Launch agents from the board and watch them.

Switching agents

Your context and stories are files, not agent state. So you can move a story from Claude Code to Codex, or back, without redoing any of them. See Switch a story between Claude Code and Codex.

Other agents

Whichever agent you run in a worktree terminal, your team’s context is already there as plain files. It reads them the way it reads any file. One-click launch and the MCP bridge wiring are built in for the two agents above, and so is the status dot (in Beta).

Coming

Launching a third CLI agent from any story, with the MCP bridge and live status wired up like the two built in. No third agent has been run end to end yet.

Unlocks with a third agent proven end to end.

Coming

The “needs you” status for agents other than the two built in.

Unlocks with an attention signal for other agents.