Merlin

Merlin Docs

Project Sessions

Extension-managed Codex and Claude sessions grouped by repo.

Project Sessions is the bundled extension for running explicit project-scoped agent work from the Claw dashboard and MCP tools. It is installed per workspace, so one Claw instance can track a different set of directories than another.

Install

claw extensions install extensions/project-sessions
claw extensions doctor
claw web run --host 127.0.0.1 --port 8787

The Projects page appears only when the extension is installed. Extension state is stored in .claw/runtime/extensions/project-sessions/state.json.

Runtime Shape

Piece Role
Project A named directory that Claw can start sessions inside.
Codex session Uses the Claw runtime with fixed openai-codex, gpt-5.5, and medium thinking.
Claude session Runs Claude Code in tmux, then projects output from Claude JSONL.
Archive Hides an idle session and closes the Claude tmux window when present.
Resume Reopens an archived session, using claude --resume for Claude.

Claude transcript reads come from ~/.claude/projects/.../*.jsonl; tmux is used for input and process control, not transcript rendering.

MCP Tools

project_sessions_add_project
project_sessions_list_projects
project_sessions_list_sessions
project_sessions_start
project_sessions_send
project_sessions_check_in
project_sessions_get
project_sessions_archive
project_sessions_resume

Use these tools instead of shelling into .claw/runtime/extensions/project-sessions/ directly.

Environment

CLAW_CODEX_COMMAND=codex
CODEX_HOME="$HOME/.codex"
CLAW_TMUX_AGENT_COMMAND="$HOME/Documents/personal/tmux-agent/tmux-agent"
CLAW_TMUX_AGENT_SESSION=project-sessions
CLAW_CLAUDE_HOME="$HOME"

Codex sessions use the Codex app-server path, so CLAW_CODEX_COMMAND can point at a specific Codex CLI and CODEX_HOME controls its auth/config directory. CLAW_TMUX_AGENT_COMMAND is optional when tmux-agent is discoverable on PATH. CLAW_TMUX_AGENT_SESSION lets all project-session windows live under a predictable tmux session. CLAW_CLAUDE_HOME should point at the directory that contains .claude/.

Agent Workflow

  1. List projects.
  2. Add the repo if it is missing.
  3. Start Codex or Claude with a short title.
  4. Send follow-up prompts to the selected session.
  5. Check in or read the saved transcript.
  6. Archive idle work; resume when needed.