dev-sessions

A CLI tool for coding agents to spawn, manage, and communicate with other coding agent sessions. Built for agent-to-agent delegation — no MCP overhead, just a CLI that agents call via Bash.

Why

Coding agents (Claude Code, Codex) are increasingly capable of orchestrating parallel work. But the tooling for agent-to-agent communication is either over-engineered (MCP servers, HTTP gateways, SSH tunnels) or too primitive (raw tmux commands).

dev-sessions provides a clean CLI interface that lets agents:

• Spawn new coding agent sessions (Claude Code or Codex)
• Send tasks and messages to those sessions
• Wait for turns to complete (transcript-aware, not terminal scraping)
• Read structured responses (clean assistant text, not ANSI noise)
• Check status (idle, working, waiting_for_input)

Installation

npm install -g dev-sessions

Or clone and link for local development:

git clone https://github.com/andrewting19/dev-sessions
cd dev-sessions
npm install && npm run build && npm link

Host Setup (one-time)

Install the gateway as a system daemon so it auto-starts on login:

dev-sessions gateway install

On macOS, grant Full Disk Access to the node binary printed by that command (System Settings → Privacy & Security → Full Disk Access). This is needed if your repos live in ~/Documents or other protected paths.

Install skills for Claude and/or Codex:

dev-sessions install-skill --global

---

Usage

# Create a session (defaults: --cli claude, --mode native)
dev-sessions create --description "refactor auth module"
# => fizz-top

# Send a task (returns immediately — non-blocking)
dev-sessions send fizz-top "Implement JWT auth. See AUTH-SPEC.md for details."
dev-sessions send fizz-top --file BRIEFING.md

# Wait for the agent to finish its turn
dev-sessions wait fizz-top --timeout 300

# Get the agent's response (clean text, not terminal noise)
dev-sessions last-message fizz-top

# Check what's happening
dev-sessions status fizz-top    # idle | working | waiting_for_input
dev-sessions list               # all active sessions

# Synchronous delegation (one-liner)
sid=$(dev-sessions create -q) && dev-sessions send $sid "run tests and fix failures" && dev-sessions wait $sid && dev-sessions last-message $sid

# Fan-out
s1=$(dev-sessions create -q --description "frontend")
s2=$(dev-sessions create -q --description "backend")
dev-sessions send $s1 "build React form per SPEC.md"
dev-sessions send $s2 "add /api/users endpoint per SPEC.md"
dev-sessions wait $s1 & dev-sessions wait $s2 & wait
dev-sessions last-message $s1
dev-sessions last-message $s2

# Codex session (persistent app-server, conversation continuity)
sid=$(dev-sessions create --cli codex -q)
dev-sessions send $sid "hello"
dev-sessions send $sid "what did I just say?"   # has context from first message
dev-sessions last-message $sid                   # "You said hello"

# Clean up
dev-sessions kill fizz-top

---

Architecture

Claude Code Sessions

• Backend: tmux (human-attachable via tmux attach -t dev-<id>)
• Session ID: Pre-assigned UUID via claude --session-id <uuid> — transcript path is known immediately
• Transcript: ~/.claude/projects/<sanitized-cwd>/<uuid>.jsonl
  • Sanitized CWD: path with / replaced by -, e.g. -Users-andrew-Documents-git-repos-myproject
• Message delivery: tmux send-keys (base64 encoded for safety)
• Turn detection: Watches for system entries in JSONL (definitive turn-completion signal)
• Status inference: last entry is assistant → idle; human/user → working; tool call to AskUserQuestion → waiting_for_input

Codex Sessions

• Backend: Persistent codex app-server daemon (JSON-RPC 2.0 over WebSocket)
• Session ID: Thread ID from thread/start response
• Conversation continuity: Multiple sends share the same thread — full history preserved
• Message delivery: turn/start JSON-RPC call (non-blocking — returns after turn/started)
• Turn detection: turn/completed notification; also thread/status/changed (Active → Idle)
• Message history: Fetched via thread/read with includeTurns: true — persisted across process restarts
• Turn status: Checked via thread/resume which returns live Thread.status
• Session liveness: Verified via thread/list — checks specific thread ID exists, not just daemon PID
• Daemon lifecycle: Auto-started on first create --cli codex, auto-stopped when last Codex session is killed

Codex App-Server Protocol

initialize → initialized → thread/start → turn/start → [stream notifications] → turn/started → ... → turn/completed

Key methods: thread/start, turn/start, turn/interrupt, thread/list, thread/resume, thread/read Key notifications: turn/started, item/agentMessage/delta, turn/completed, thread/status/changed

ThreadStatus JSON shape — important, easy to get wrong:

• "idle", "notLoaded", "systemError" serialize as plain strings
• "active" serializes as { "active": { "activeFlags": [...] } } — a tagged enum variant
• Do NOT look for a .type field — that's the wrong shape

Champion IDs

Sessions get human-readable IDs like fizz-top, riven-jg (League of Legends champion + role). These map to internal UUIDs/thread IDs but are easier to type and remember.

Session Store

Persisted at ~/.dev-sessions/sessions.json. All mutating operations use file-based locking (mkdir as atomic primitive) to serialize concurrent access.

---

Commands

Command	Description
create [options]	Spawn a new agent session (`--cli claude
send <id> <msg>	Send a message — returns immediately after delivery (--file to send file contents)
wait <id>	Block until current turn completes (--timeout seconds, --interval poll interval)
last-message <id>	Get last N assistant messages (-n count)
status <id>	Get session status: idle, working, or waiting_for_input
list	List all active sessions (--json for machine-readable output)
kill <id>	Terminate a session and clean up
gateway	Start the Docker relay gateway HTTP server (--port)
gateway install	Install gateway as system daemon (launchd on macOS, systemd on Linux)
gateway uninstall	Remove gateway daemon
gateway status	Check if gateway daemon is running and on which port
install-skill	Install all skills (--global|--local, --claude|--codex)

Modes

Mode	Flag	Description
native	--mode native	Runs with --dangerously-skip-permissions — auto-approves all tool calls (default)
docker	--mode docker	Runs via clauded Docker wrapper (Claude Code only)

Session Lifecycle

create  →  send  →  [wait / poll status]  →  last-message  →  kill
                ↑                                    |
                └────────────────────────────────────┘
                        (send follow-up)

send is non-blocking — it returns immediately after the message is delivered. Use wait to block until the turn completes.

---

Docker Integration

Running FROM inside a container

When running inside a Docker container (detected via DEV_SESSIONS_SANDBOX=1), the CLI automatically routes all commands through an HTTP gateway relay on the host.

Setup:

1. On the host: dev-sessions gateway install (or manually dev-sessions gateway --port 6767)
2. Inside Docker, set DEV_SESSIONS_GATEWAY_URL=http://host.docker.internal:6767
3. Set HOST_PATH to the host-side project path (e.g. /Users/you/project)

Path translation: Container paths are automatically mapped to host paths. When an agent inside Docker passes --path /workspace/subdir, it's translated to HOST_PATH/subdir before being sent to the gateway. This means agents can use paths as they see them locally without knowing the host filesystem layout.

Environment Variable	Default	Purpose
DEV_SESSIONS_SANDBOX	—	Set to 1 to enable gateway mode
HOST_PATH	—	Host-side path that /workspace maps to
CONTAINER_WORKSPACE	/workspace	Container mount point (override if using a different mount path)
DEV_SESSIONS_GATEWAY_URL	http://host.docker.internal:6767	Gateway endpoint

The gateway binds to 127.0.0.1 only — not exposed beyond loopback.

--mode docker (spawning Claude in a container)

Spawns Claude inside Docker via a clauded binary on the host. See claude-ting for a reference Docker wrapper.

Note: If clauded is defined as a shell function in .zshrc, create a wrapper script so tmux (bash) can find it:

#!/bin/zsh
source ~/.zshrc 2>/dev/null
claude-docker "$@"

at ~/.local/bin/clauded.

---

Known Limitations

• Codex ignores --mode: Always runs with approvalPolicy: never / full access regardless of mode flag.
• docker mode is Claude-only: Codex + Docker not implemented.
• Session store uses file locking: Concurrent operations are serialized via lockfile. A crashed process holding the lock is auto-recovered after 30 seconds.
• Gateway port conflict: Default port 6767 can conflict with Docker. Use DEV_SESSIONS_GATEWAY_PORT to override.
• No respond command: No structured way to respond to waiting_for_input sessions. Only matters for non-native modes.
• Claude permission prompts undetectable: TUI-level prompts aren't written to JSONL — status reports working instead of waiting_for_input. Only affects native mode.

---

Development

npm install
npm run build
npm test        # 123 unit + integration tests
npm link        # link global dev-sessions to this repo's dist/

See CLAUDE.md for developer workflow standards and TODO.md for current project state and remaining work.

License

MIT