Claude Code Sessions
Run the Claude Code CLI from the Dashboard or the Sophon CLI, follow its event stream, and share one Claude login between Sophon and Claude Code.
Claude Code Sessions let you send work to Anthropic's Claude Code CLI (claude) through your Gateway and watch what it does. You write a message, the Gateway runs Claude Code in a working directory you choose, and the replies, tool calls and results stream back to you as events.
This page covers the interactive sessions on the Dashboard's Claude Code page and the sophon claude-code commands. To let an agent hand a coding task to Claude Code, see Coding Agents. For Sophon's own coding agent, see The coding agent.
The Gateway runs Claude Code with --permission-mode bypassPermissions, outside Sophon's approval gates. By default (Sophon:CodingAgents:Mode = Process) it runs directly on the Gateway host. The working directory you give it is used as-is: it is not confined to a workspace root. Only Container mode runs Claude Code in a separate runner container. Treat access to this page like shell access to the Gateway host.
What's in a session
- A session id. The Gateway passes it to Claude Code as
--session-idand lists the session under it. - A working directory. A path on the Gateway host where Claude Code runs. When you leave it empty, the Gateway uses
Sophon:ClaudeCode:CodingAgent:WorkspaceRoot, or its own current directory when that is not set. - A model. Defaults to
Sophon:ClaudeCode:DefaultModel(sonnet). - A tool list. Claude Code may use
Read,Write,Edit,Bash,GlobandGrepby default (Sophon:ClaudeCode:CodingAgent:AllowedTools). - An event stream. Each reply, tool call and tool result arrives as an event over SignalR.
The Claude Code integration must be turned on (Sophon:ClaudeCode:Enabled), and the claude binary must be installed on the Gateway host (or in the runner image, in Container mode). Otherwise sending a message fails with "Claude Code integration is disabled." or "Claude Code CLI is not installed."
Starting a session
From the Dashboard
Open the Claude Code page and click New Session (or + in the Sessions list). Optionally enter a working directory in the bar above the chat, then type a message. While Claude Code works, the session shows a Streaming badge and the events appear in the chat area.
From the CLI
The CLI sends messages and follows the stream. It does not create sessions; use a session id from the Dashboard or from POST /api/claude-code/sessions.
sophon claude-code sessions
sophon claude-code send <sessionId> "Add a retry policy to the HTTP client" \
--working-directory /srv/repos/my-app \
--model sonnet
sophon claude-code stream
sophon claude-code end <sessionId>send returns as soon as the Gateway accepts the message and prints "Message sent." Run sophon claude-code stream in another terminal to see the reply. --working-directory is a path on the Gateway host, and --model falls back to Sophon:ClaudeCode:DefaultModel. end only acknowledges that you are done with the session.
Fixed in v2.1.0. sophon claude-code send failed on every call in v2.0, because it sent a body the Gateway rejected. It now sends { message, workingDirectory?, model? } and has the --working-directory and --model options. The help text no longer calls the run "sandboxed".
Event streams
The Gateway sends ClaudeCodeStreamStart, then one ClaudeCodeEvent per item, then ClaudeCodeStreamEnd. Each ClaudeCodeEvent has a type and, depending on the type, content, toolName, toolInput, toolResult or fileChange:
type | Fires when |
|---|---|
assistant | Claude Code writes text |
tool_use | Claude Code calls a tool (Edit, Bash, Grep, …) |
tool_result | The tool returns |
result | The run finishes |
error | The run fails |
Other types that Claude Code emits are passed through with only content.
Since v2.1.0, sophon claude-code stream and the full-screen CLI read these fields correctly, through one formatter that strips control characters and shortens long values. One limit remains on the Gateway side: it reads only top-level text fields from Claude Code's output. A real claude binary nests much of its text and its tool calls inside a message object, so some replies, tool lines and file changes may arrive empty or not appear.
One login shared with Claude Code
Sophon and the claude CLI on the same host use one Claude login. When the Gateway refreshes an expired Claude Code token, or you log in to Claude from the Dashboard, Sophon writes the new tokens into Claude Code's own credential store:
| Platform | Store |
|---|---|
| macOS | The login Keychain, item Claude Code-credentials |
| Windows and Linux | $CLAUDE_CONFIG_DIR/.credentials.json when CLAUDE_CONFIG_DIR is set, else ~/.claude/.credentials.json |
The Sophon Docker images set CLAUDE_CONFIG_DIR to config/claude inside Sophon's data directory, so the file lives on the data volume.
In v2.0 these writes could leave Claude Code saying "Not logged in · Please run /login". Since v2.1.0 they keep Claude Code logged in:
- A refresh merges. It changes only the token fields, plus
scopesandemailwhen they are known. Every other field Claude Code keeps in the file stays. - A Dashboard login replaces the account fields. The new login may be a different account, so it drops
subscriptionType,rateLimitTier,refreshTokenExpiresAtandemailbefore writing the new login's values. Other keys stay. - The file is replaced whole. Sophon writes a temp file and moves it over the store, so Claude Code never reads a half-written file. The file has no byte-order mark. A symlinked store is written at its target, and the link stays.
- The file keeps its Unix mode. An existing file keeps its mode. A new file is owner-only (
0600). - A damaged store is replaced. A store that is not a JSON object (an empty or cut-off file, for example) is overwritten instead of failing every later write. The Gateway logs a warning that names the store but not its content.
- The Keychain entry keeps its quotes. On macOS the JSON is passed to
securityas one argument, so it stays valid. The write targets the account of the existingClaude Code-credentialsitem, or your login user name when there is none. No automated test runs this path on a Mac.
If Claude Code still says "Not logged in"
Run /login in Claude Code once, or log in again from the Dashboard. On macOS this is needed if an older Gateway already refreshed your token: the Keychain entry it wrote has lost its quotes, and the Gateway cannot refresh from an entry it cannot read.
Downgrading to an older Gateway brings back the old writes, and with them the login prompts.
Container mode on Linux
In Container mode the Gateway (user sophon) writes the file and the Claude Code runner (user runner) reads it from <data dir>/config/claude, mounted at /home/runner/.claude. A file the Gateway creates is owner-only, so the runner cannot read it until you grant access once.
Each write replaces the file, which keeps the mode but not the group. A chgrp on the file alone is undone by the next refresh. Give the directory the shared group and the setgid bit, so new files inherit it:
# once, on the host; <data dir> is Sophon's data directory
sudo chgrp sophon-claude <data dir>/config/claude
sudo chmod g+s <data dir>/config/claude
sudo chgrp sophon-claude <data dir>/config/claude/.credentials.json
sudo chmod 0640 <data dir>/config/claude/.credentials.jsonBoth users must be in the sophon-claude group (the name is an example). Alternatively, make the shared group the Gateway user's primary group.
See Subscriptions for using your Claude subscription as a model provider.
Use cases
- Refactor a project. Point the session at a repository, let Claude Code analyze it, make the change and run the tests.
- Prototype a feature. Scaffold a module, write tests, and iterate until they pass.
- Debug a failing test. Point Claude Code at the test and let it investigate and propose a fix.
Limits and gotchas
- No isolation in the default
Processmode: Claude Code runs as the Gateway's user on the Gateway host, withbypassPermissions, in whatever directory you give it. - The session list is kept in the Gateway's memory.
- The CLI cannot create sessions;
sendneeds an existing session id. - A run is stopped after 10 minutes (
Sophon:ClaudeCode:CodingAgent:Timeout, in seconds), or after 2 minutes with no output (NoOutputTimeout). Turns are capped at 25 by default (DefaultMaxTurns, hard limit 100). - Some tool and file events may not show up in the stream (see Event streams).
From agents
Chat agents can hand a coding task to Claude Code with the coding.claude_code tool. It is rated High risk, so under the default approval settings it waits for your approval. See Coding Agents.
Where to go next
- Coding Agents — let an agent delegate work to Claude Code, Codex or Copilot
- The coding agent — Sophon's own coding agent in the CLI, with diff approvals and
/rewind - Subscriptions — use your Claude subscription as a model provider