Claude Code Sessions
Sandboxed development sessions where Claude builds, tests, and iterates on persistent multi-file projects.
Claude Code Sessions pair Claude with a managed development environment — a sandboxed workspace with persistent file state, a git repository, shell access, and streaming events for every action Claude takes. It's the right surface when you want Claude to build a real project (not just write a snippet) and you want to see every file change, tool call, and reasoning step as it happens.
Think of it as Canvas's bigger sibling: Canvas is one-shot artifacts; Claude Code is a working directory where Claude lives for the duration of the session.
What's in a session
Each session has:
- Project directory — an isolated sandbox filesystem, persistent across turns until the session is deleted.
- Git repo — initialized on session start, so Claude can commit and you can diff.
- Event stream — every user message, assistant message, tool call, tool result, and file change is streamed as an event.
- Shell — Claude can execute shell commands against the sandbox (approved-gated on first use per session).
- Integrated editor — Monaco view of any file, with live sync as Claude edits.
Starting a session
From the Dashboard
Operations → Claude Code → New Session. Fill in:
- Session name
- Starter — empty / clone a repo / from template
- Base image — which sandbox (Python, Node, .NET, generic)
- Model — which Claude version (Opus, Sonnet, Haiku)
- System prompt — optional custom instructions
Click Start. You're dropped into the session with an empty chat and the project tree in the left rail.
From the CLI
sophon claude-code new --name "refactor-api" --base node
sophon claude-code list
sophon claude-code stream <session-id> # tail the event stream
sophon claude-code exec <session-id> "npm test"
sophon claude-code delete <session-id>Event streams
A Claude Code session emits a typed event stream. Consumers (Dashboard, CLI, custom tooling) subscribe and react:
| Event | Fires when |
|---|---|
user | You send a message |
assistant | Claude sends a message |
tool_use | Claude invokes a tool (Edit, Bash, Glob, Grep, …) |
tool_result | The tool returns |
file_change | A file in the project was created / modified / deleted |
session_start, session_end, session_error | Lifecycle |
The Dashboard's right pane shows this stream with folding for tool results, syntax-highlighted file diffs, and expandable reasoning blocks.
Tools available to Claude
A Claude Code session exposes a focused tool surface:
- Read / Edit / Write — files in the project directory
- Glob / Grep — search by pattern or content
- Bash — shell commands in the sandbox
- TaskCreate / TaskUpdate — Claude's own task list for multi-step work
Unlike chat agents, Claude Code sessions don't share the general-purpose Sophon tool registry by default — the session is scoped to building code, not sending emails or calling Gmail. You can opt into external tools per session in the session settings if the work needs them.
Persistence
The project directory survives across turns and across Gateway restarts. When you re-open a session, you're in the same directory, same git history, same files. Sessions are per-user; nobody else sees yours.
Delete a session to remove its project directory. There's no recover — snapshot first with:
sophon claude-code export <session-id> --out ./archive/Cost and isolation
Each session runs in its own sandbox container with:
- CPU + memory limits (configurable per base image)
- No access to host filesystem
- Network rules per base image (Node sessions can fetch npm, Python can fetch pip, generic is network-off)
- A 2-hour idle auto-shutdown (pipeline is reloaded on next turn)
Tokens are billed to the user's budget (BudgetMiddleware) just like any other agent run. A long refactor session can consume significant tokens — watch the session detail view's Token usage chart.
Use cases
- Refactor project X — clone the repo, let Claude analyze, propose a plan, execute changes, run tests, commit.
- Prototype a feature — scaffold a new module, write tests, iterate until green.
- Debug a failing test — point Claude at a failing test, let it investigate and propose a fix.
- Port between languages — "convert this Python module to TypeScript." Claude has real tooling to run the output.
Limits and gotchas
- No multi-user sessions — one user per session.
- No remote repository push from inside the sandbox. You commit locally;
sophon claude-code exportpulls the repo out, and you push from your machine. - Bash commands that hang indefinitely time out at 10 minutes. Use
nohupor background jobs if you need long-running processes — but note the sandbox shuts down after 2 hours of idle. - Don't store secrets in the sandbox. The session uses
.envfiles by convention; the Dashboard has a Secrets tab per session that injects env vars at runtime without exposing them in the file tree.
From agents
Chat agents can spawn Claude Code sessions as a tool: claude_code.start creates a session, claude_code.send sends a message and returns Claude's response. Useful for orchestrating a higher-level agent that delegates code work to Claude.