Self-improving AI Employees for everyone
Claude Code Agent — Documentation Hub
claude_code_agent is a OpenCompany agent node that drives the real claude CLI as a
long-lived interactive subprocess (stdio pipes, no PTY) over the VSCode-extension
stream-json protocol — not the claude -p headless path. A warm ClaudeSessionPool
(keyed by the RFC-0002 conversation key when a Context node is connected, or by the
legacy simpleMemory.node_id on input-memory graphs — services/cli_agent/service.py:359-363)
preserves the session across turns;
memory continuity is claude-native via a host-minted --session-id on the first run and --resume <last_session_id> afterwards in a stable
per-workflow git worktree (<workspace>/<node>/wt_session, branched off the enclosing repo; the repo root is never the cwd). Connected tools and skills reach claude through an MCP bridge; the spawn
runs under --permission-mode dontAsk with a strict --allowedTools allowlist and stays
in interactive billing (entrypoint claude-vscode, not sdk-cli).
This page is a router. The detail lives in the documents below — start here, then jump.
Where to read what
| Your question | Read |
|---|---|
| How does the whole integration work end-to-end? (architecture, memory & context compaction, sub-agent creation, data structures) | claude_code_agent_architecture.md |
How does interactive mode work? (stdio pipes vs PTY, stream-json events, system/init / assistant / result, session continuity, the four claude.session.* CloudEvents) |
claude_code_interactive_mode.md |
The generic multi-provider runtime (AICliService.run_batch, FastMCP bridge, the memory bridge --session-id/--resume, plugin-folder layout) |
cli_agent_framework.md |
| Does our implementation match the official Claude Code spec? (six invariants + status) | cli_agent_canonical_patterns_rfc.md |
| Which CLI subcommands/flags exist, and which subset we emit | claude_code_cli_reference.md (snapshot) |
Environment variables (CLAUDE_CONFIG_DIR, MAX_MCP_OUTPUT_TOKENS, ENABLE_TOOL_SEARCH, Bedrock/Vertex, telemetry) |
claude_code_env_vars_reference.md (snapshot) |
Permission-mode semantics (default / acceptEdits / plan / dontAsk / bypassPermissions); why OpenCompany uses dontAsk |
claude_code_permission_modes_reference.md (snapshot) |
Headless / print mode (claude -p, --output-format, stream-json event schema) — the schema the pool parses off stdout |
claude_code_headless_reference.md (snapshot) |
SKILL.md frontmatter spec, discovery paths, context: fork — what we materialise skills against |
claude_code_skills_reference.md (snapshot) |
The five cli-reference / env-vars / permission-modes / headless / skills
documents are verbatim snapshots of code.claude.com docs (fetched 2026-05-11), kept so
the contract the pool parses is pinned even if upstream changes.
Plugin folder — server/nodes/agent/claude_code_agent/
All claude-specific code is self-contained here; the generic framework at
server/services/cli_agent/ imports nothing from nodes/.
| File | Responsibility |
|---|---|
__init__.py |
ClaudeCodeAgentNode(ActionNode) (line 238 — it does not go through SpecializedAgentBase / the native loop) + Params/Output; self-registers via factory.py (register_provider / register_session_pool / register_skill_materialiser) + register_ws_handlers. |
_provider.py |
Builds the spawn argv (--output-format stream-json --input-format stream-json --verbose --ide, --permission-mode dontAsk, --allowedTools, --resume/--session-id). |
_pool.py |
ClaudeSessionPool — warm subprocess keyed by the RFC-0002 conversation key context_bridge.pool_key (legacy fallback: simpleMemory.node_id); stdout reader, session-UUID capture, crash-recovery respawn. |
_skills.py |
materialise_skills — writes connected SKILL.md trees under <workspace>/.claude/skills/, diff-based on warm reuse. |
_oauth.py |
Isolated CLAUDE_CONFIG_DIR (<DATA_DIR>/claude/), browser-OAuth bridge, binary install. |
_handlers.py |
WebSocket handlers handle_claude_code_login / handle_claude_code_logout, exported through WS_HANDLERS. |
See also
- Memory bridge specifics (how
simpleMemory.last_session_idfeeds--resume, why--continueis never used): cli_agent_framework.md → Memory bridge. - Generic CLI agent runtime shared with Codex / Gemini providers:
server/services/cli_agent/.