Self-improving AI Employees for everyone
AI CLI Agent Framework
Multi-instance, multi-provider runtime for AI CLI agents (Claude Code, Codex, Gemini). One workflow node spawns N parallel CLI sessions over a list of tasks, each isolated in its own git worktree, each able to call back into OpenCompany over MCP.
| Provider | Status | Login flow |
|---|---|---|
Claude Code (@anthropic-ai/claude-code) |
shipping | Shared-tree install + spawn (nodes/agent/claude_code_agent/_oauth.py:run_claude_login) |
OpenAI Codex (@openai/codex) |
fails on every run (see Risks); no login flow yet | User runs codex login manually; UI returns a graceful "not yet wired" error |
Google Gemini (@google/gemini-cli) |
v2 stub | factory raises NotImplementedError |
Browser automation has its own runtime (the installed Chrome/Edge/Chromium by default, plus a uv-installed browser-use CLI); it is not installed into this bun package tree. See browser.md and browser_workspace.md for its lifecycle and live control surface.
Architecture
ClaudeCodeAgentNode (claude_code_agent) CodexAgentNode (codex_agent)
│ Params.tasks: list[ClaudeTaskSpec] list[CodexTaskSpec]
▼
AICliService.run_batch(provider, tasks, *, node_id, workflow_id, workspace_dir)
│ provider = create_cli_provider(name) ("claude" | "codex" | "gemini"→NotImpl)
│ allocate per-batch bearer token; register BatchContext in MCP token registry
│ asyncio.gather under Semaphore(max_parallel, default 5)
│
├──► claude (registered session pool) → ClaudeSessionPool via _run_pooled_turn
│ run_pooled(): git worktree add <workspace>/<node>/wt_session (bound)
│ or wt_<run>_<i> per task (ephemeral, removed after the batch)
│ pool.acquire(): cold spawn over stdio pipes, or warm reuse
│ argv: --mcp-config <json> (MCP bearer) ... --ide (no lockfile written)
│ env: the backend's os.environ + CLAUDE_CONFIG_DIR + OPENCOMPANY_PARENT_RUN_ID
│ pool.send_turn(): stream-json line on stdin, wait for `result` on stdout
│
└──► codex (no session pool) → AICliSession (BaseProcessSupervisor + CodexProvider)
_do_start(): binary check, then _pre_spawn() (git worktree add; lockfile
only if the provider declares `ide_lockfile`, Codex does not),
then raises for every provider except claude, so the run fails
cleanup(): terminate_then_kill(5s) + worktree remove
│
│ ◄──── CLI calls back via MCP/HTTP at /mcp/ide/mcp
│ Authorization: Bearer <batch-token> (per-batch isolation)
│ tools: getWorkspaceFiles, listSkills, getSkill, readSkillResource,
│ searchSkillResource, getCredential, broadcastLog
▼
BatchResult { tasks: [SessionResult, ...], n_succeeded, n_failed, total_cost_usd?, wall_clock_ms }
│ token deregistered in finally (non-pool path; a pooled session keeps its
│ spawn-time token until _terminate_locked)
▼
Temporal keeps the long run alive with activity heartbeats (the per-type activity's periodic
heartbeat in BaseNode; the legacy execute_node_activity path heartbeats while waiting in
NodeExecutionActivities._execute_via_websocket)
SessionResult.response is truncated to 4000 chars where the result is built
(ClaudeSessionPool._build_result_from_events; AICliSession does the same)
Reuses (do not duplicate):
services/_supervisor/{base,process,util}.py—BaseProcessSupervisor(locked start/stop,kill_tree,terminate_then_kill(5s), drain tasks, WindowsCTRL_BREAK_EVENT)services/llm/{protocol,registry,config}.py— Protocol + lazyregister_provider(ProviderSpec)registry + JSON config blueprint (the oldllm/factory.pywas removed)services/handlers/tools.py—_execute_check_delegated_tasksapplies the same 4000-char cut to delegated-agent resultsservices/status_broadcaster.py—update_node_status,broadcast_terminal_logservices/skill_loader.py—scan_skills/load_skillconsumed by MCPlistSkills/getSkillservices/auth.py—AuthService.get_api_keyconsumed by MCPgetCredentialservices/credential_registry.py— deep-mergeextendsfor_cli_baseentrynodes/agent/claude_code_agent/_oauth.py— Claudeauth login/auth status/auth logoutwrappers,bun add(viacore/js_runtime.add_package,trust=True) into the shared OpenCompany packages tree at<DATA_DIR>/packages/(binary resolves to<DATA_DIR>/packages/node_modules/.bin/claude[.exe]and runs on bun),CLAUDE_CONFIG_DIR=<DATA_DIR>/claude/. Theloginspawn passesstdin=PIPE(un-written) so the native CLI's stdin reader blocks instead of EOFing — keeps its localhost OAuth callback server alive until the browser flow completesnodes/stripe/_handlers.py— pattern reference for marker-token + catalogue broadcast
Generation Stop and CLI session resume
CLI agent nodes remain whole-node Activities in Temporal, outside
AGENT_WORKFLOW_TYPES. New generation control (execution_control_version=1)
closes admission before later node/tool Activities and waits for an admitted CLI
Activity, including its subprocess and MCP work, to settle under its scheduled
policy. Result bookkeeping completes normally before the graph/parent agent
waits. Generation Resume releases the existing continuation; it does not create
a replacement CLI task or repeat a recorded completed Activity.
Claude's native --resume <session_id>, warm session reuse, and pool crash
recovery are separate provider/session mechanisms described below. Generation
Stop does not pause between CLI-internal tools, and heartbeat strings cannot
serialize the subprocess or JSONL session. External effects before recorded
completion remain governed by retry/idempotency. Legacy generations retain
their earlier control behavior. See Temporal workflow control,
Temporal architecture,
and the Claude Code node card.
Provider abstraction (mirrors services/llm/)
# server/services/cli_agent/protocol.py
@runtime_checkable
class AICliProvider(Protocol):
name: str
package_name: str
binary_name: str
ide_lock_env_var: Optional[str] # CLAUDE_IDE_LOCK | GEMINI_IDE_LOCK | None
ide_lockfile_dir: Optional[Path] # <DATA_DIR>/claude/ide | <tmpdir>/gemini/ide
def binary_path(self) -> Path: ...
def interactive_argv(self, task, *, defaults) -> list[str]: ...
def login_argv(self) -> list[str]: ... # CLI's own login command
def auth_status_argv(self) -> Optional[list[str]]: ... # cheap probe
def detect_auth_error(self, stderr, exit_code) -> bool: ...
def parse_event(self, line: str) -> Optional[dict]: ...
def is_final_event(self, event: dict) -> bool: ...
def event_to_session_result(self, events, stderr, exit_code) -> dict: ...
# Returns: {...shared, "provider_data": {<vendor-specific>}}
# provider_data carries Anthropic reasoning_details, Codex call_id,
# Gemini extra_content — pattern from Hermes agent/transports/types.py.
def canonical_usage(self, events) -> CanonicalUsage: ...
# Normalises vendor token-counting; feeds services/pricing.py.
def supports(self, feature: str) -> bool: ...
# max_budget | max_turns | session_id | resume | mcp_runtime
# | json_cost | ide_lockfile | sandbox
Claude argv (AnthropicClaudeProvider.interactive_argv)
Spawned per task — the binary path comes from
nodes.agent.claude_code_agent._oauth.claude_binary_path() (the same
project-local install the credentials Login button uses) and CLAUDE_CONFIG_DIR is
injected on the spawn env so the agent shares one credential store with
the auth surface.
The pooled path (ClaudeSessionPool) spawns claude as a plain
subprocess with stdio pipes — no PTY — and drives it over the
VSCode-extension protocol: prompts written as stream-json to
proc.stdin, events read as stream-json off proc.stdout. -p /
--print is never emitted. The expectation that this keeps usage in
the interactive billing bucket (entrypoint claude-vscode, not
sdk-cli) is unverified.
~/.opencompany/packages/node_modules/.bin/claude[.exe] # bun's bin shim; runs on bun
--output-format stream-json # events on stdout
--input-format stream-json # user turns to stdin as JSON
--verbose # required with stream-json for full event detail
--ide # matches the VSCode extension; no lockfile is written, MCP rides --mcp-config
--model <model>
[--resume <UUID> | --continue | --session-id <UUID>] # mutually exclusive, in that precedence
--allowedTools <csv>
--permission-mode <mode>
[--append-system-prompt <text>]
[--effort <low|medium|high|xhigh|max>]
[--add-dir <path>]* [--disallowedTools <csv>] [--agent <name>]
[--mcp-config <json>] [--strict-mcp-config]
Dropped from the pool path (vs. the previous headless/-p shape):
-p, --print, --include-partial-messages, --include-hook-events,
--max-turns, --max-budget-usd, --fallback-model. The positional
-- "<prompt>" is also never emitted — prompts arrive as JSON on
stdin ({"type":"user","message":{"role":"user","content":"..."}}\n).
ClaudeTaskSpec keeps the corresponding Pydantic fields for
back-compat; they're silently dropped in interactive_argv.
All flags documented at
code.claude.com/docs/en/cli-reference.
Skill materialisation and the bearer-token MCP server are wired in
nodes/agent/claude_code_agent/_pool.py:_spawn. Every Claude run
routes through the pool (AICliService.run_batch): memory- or
Context-bound runs get one warm session keyed by the conversation;
unbound runs get one ephemeral session per task keyed by
<node_id>:<turn_execution_id>:<index> and terminated once the batch
settles. AICliSession (PTY + on-disk JSONL watcher) is no longer used
for Claude — a PTY stdin makes the CLI reject stream-json input, and
that path never wrote the prompt (GitHub issues #133 / #134).
Session identity follows the CLI reference: a cold spawn mints
--session-id <uuid4> so the UUID is known before the first event;
memory-bound runs pass --resume <last_session_id> (persisted on the
memory node by _persist_memory). The node's continuity logic never
uses --continue, because the CLI skips non-interactively created
sessions when resolving it; it is still emitted if a task in the node's
tasks list sets continue_session: true. A child
that exits without a result event wakes send_turn on stdout EOF and
reports the exit code instead of burning the turn timeout.
Factory — a registry lookup, not a hardcoded branch per provider. Each plugin
calls register_provider(name, factory) on import (claude from
nodes/agent/claude_code_agent/__init__.py, codex from
services/cli_agent/__init__.py); re-registering a different factory under an
existing name raises:
# server/services/cli_agent/factory.py (create_cli_provider)
def create_cli_provider(name: str) -> AICliProvider:
factory = _PROVIDER_REGISTRY.get(name)
if factory is not None:
return factory()
if name == "gemini": # known-but-deferred, so the dropdown can grey it out
raise NotImplementedError("gemini provider deferred to v2. Use 'claude' or 'codex' in v1.")
raise ValueError(f"Unknown CLI provider: {name!r}. Registered: {sorted(_PROVIDER_REGISTRY)}. ...")
is_supported(name) # name in _PROVIDER_REGISTRY
registered_provider_names() # frozenset snapshot
Task specs (discriminated union)
# server/services/cli_agent/types.py
class BaseAICliTaskSpec(BaseModel):
task_id: Optional[str] = None
prompt: str
branch: Optional[str] = None
model: Optional[str] = None
timeout_seconds: int = Field(600, ge=10, le=3600)
system_prompt: Optional[str] = None
# Strict input validation: typo'd task fields raise ValidationError
# at the spec boundary instead of being silently dropped.
model_config = ConfigDict(extra="forbid")
class ClaudeTaskSpec(BaseAICliTaskSpec):
provider: Literal["claude"] = "claude"
session_id: Optional[str] = None
resume_session_id: Optional[str] = None
continue_session: bool = False # emits --continue; see Session identity
max_turns: Optional[int] = None
max_budget_usd: Optional[float] = None
allowed_tools: Optional[str] = None # default: "" — see "Strict allowlist"
permission_mode: Literal["default", "acceptEdits", "plan", "auto",
"dontAsk", "bypassPermissions"] = "dontAsk"
# Optional documented CLI flags
effort: Optional[Literal["low", "medium", "high", "xhigh", "max"]] = None
fallback_model: Optional[str] = None
add_dir: List[str] = Field(default_factory=list)
disallowed_tools: Optional[str] = None
agent: Optional[str] = None
class CodexTaskSpec(BaseAICliTaskSpec):
provider: Literal["codex"] = "codex"
sandbox: Literal["read-only", "workspace-write", "danger-full-access"] = "workspace-write"
ask_for_approval: Literal["untrusted", "on-request", "never"] = "never"
class GeminiTaskSpec(BaseAICliTaskSpec):
provider: Literal["gemini"] = "gemini"
session_id: Optional[str] = None
resume: Optional[str] = None
yolo: bool = False
sandbox: bool = False
AICliTaskSpec = Annotated[
Union[ClaudeTaskSpec, CodexTaskSpec, GeminiTaskSpec],
Field(discriminator="provider"),
]
Each plugin's Params.tasks is hard-typed to one variant — the LLM tool-schema plugin fast-path in _get_tool_schema (services/ai.py) produces a clean per-provider schema (no $defs/$ref).
Auth model — Stripe-style CLI-managed OAuth
CLI auth is delegated to the CLI's own login flow + a synthetic marker token in OpenCompany's catalogue. Mirrors nodes/stripe/_handlers.py (commit a32f671).
Per-provider WS handler names (Twitter / Google / Stripe convention — frontend dispatches {} payload, handler name encodes provider):
| Catalogue id | Login handler | Logout handler |
|---|---|---|
claude_code |
claude_code_login |
claude_code_logout |
codex_cli |
codex_cli_login (returns "not yet wired") |
codex_cli_logout |
Claude flow (handle_claude_code_login and handle_claude_code_logout in server/nodes/agent/claude_code_agent/_handlers.py) uses the documented CLI subcommands from code.claude.com/docs/en/cli-reference:
| Subcommand | Purpose |
|---|---|
claude auth login |
Opens the browser, writes credentials |
claude auth status |
Exits 0 when logged in, 1 otherwise |
claude auth logout |
Clears credentials |
Steps:
- Run
claude auth status. If it exits 0, write the marker + broadcast and return immediately (idempotent re-click). - Otherwise schedule
_finalize_claude_login()(innodes/agent/claude_code_agent/_handlers.py), which callsrun_claude_login()from_oauth.py:- OpenCompany-managed install of
@anthropic-ai/claude-codeinto the shared packages tree at<DATA_DIR>/packages/viacore.js_runtime.add_package("<package_name>@<package_version>", trust=True)—bun add --cwd <packages_dir> --no-progress --trust <spec>(same tree asedgymeow/cf/vercel; skipped if already installed;--trustbecause the package's postinstall stages its native launcher, which bun otherwise blocks). The exact version is pinned inserver/config/ai_cli_providers.json(package_version, the vercel / cloudflare idiom) because the stream-json contract and flag surface are verified against that version only. Binary resolves to<DATA_DIR>/packages/node_modules/.bin/claude[.exe]and runs on bun — no Node or npm involved (claude-code 2.1.258 verified on bun with no Node on PATH). claude auth loginviarun_cli_command(..., env={..., CLAUDE_CONFIG_DIR=<DATA_DIR>/claude/}, stdin=asyncio.subprocess.PIPE)— same way the VSCode Claude Code extension delegates to the binary. Anthropic doesn't expose--print-urlor a programmatic OAuth helper (issue anthropics/claude-code#7100, closed "not planned"), so we let the CLI open the user's browser via its own OS-level call.stdin=PIPEis load-bearing for claude-code >= 2.1.162's native binary: it reads stdin while waiting for the browser callback, and an inherited (closed) stdin EOFs it into an early exit that kills the localhost callback server before the redirect arrives —stdin=PIPE(never written) makes the read block so the server stays up.
- OpenCompany-managed install of
- Schedule a background task that polls
claude auth statusevery 2s up to 600s. On exit-0, write the synthetic"cli-managed"marker viaauth_service.store_oauth_tokens("claude_code", ...)and broadcastcredential_catalogue_updated. The catalogue'sstoredflag flips and the existingOAuthConnect.tsxprimitive renders the modal as Connected.
Logout: runs claude auth logout, drops the marker via auth_service.remove_oauth_tokens(), and broadcasts.
Codex login: not yet wired. The handler returns a graceful error pointing the user at bun add -g @openai/codex + codex login manual flow (the provider itself falls back to bun x @openai/codex when no system codex is on PATH). Follow-up: mirror nodes/agent/claude_code_agent/_oauth.py for codex with a HOME=<DATA_DIR>/codex/ env redirect (Codex has no CONFIG_DIR equivalent).
Frontend: no changes. The existing client/src/components/credentials/primitives/OAuthConnect.tsx already documents and supports the Stripe-style fieldless-CLI case (config.fields = [], kind: "oauth", stored flag drives Connected state).
VSCode-style IDE MCP server
Claude reaches OpenCompany's MCP server through the --mcp-config entry in its argv (URL plus bearer header). No custom IPC.
The VSCode-style lockfile (lockfile.py) is written only by AICliSession._pre_spawn, and only for a provider that declares ide_lockfile. Claude declares it but never runs through AICliSession, Codex does not declare it, and Gemini is a stub, so in practice no lockfile is written today. For reference, the path is <DATA_DIR>/claude/ide/<pid>.lock (Claude — AnthropicClaudeProvider.ide_lockfile_dir = OPENCOMPANY_CLAUDE_DIR / "ide", so it sits under the isolated CLAUDE_CONFIG_DIR, not the user's ~/.claude/) or <tmpdir>/gemini/ide/gemini-ide-server-<pid>-<port>.json (Gemini, v2). Format mirrors VSCode (write_ide_lockfile in lockfile.py):
{
"port": <PYTHON_BACKEND_PORT>,
"url": "http://127.0.0.1:<PYTHON_BACKEND_PORT>/mcp/ide/mcp",
"authToken": "<32-byte hex>",
"workspaceFolders": ["<repo_root for memory-bound runs, else the per-task git worktree>"],
"ideName": "claude",
"transport": "http",
"pid": 12345
}
Two fields are load-bearing. The url MUST end in /mcp/ide/mcp: FastMCP's streamable_http_app() registers the JSON-RPC route at /mcp of the sub-app and main.py mounts the sub-app at /mcp/ide, so the older /mcp/ide form silently 404'd before the request reached the bearer-token middleware. ideName is the provider name (AICliSession._pre_spawn passes self._provider.name), not "opencompany". The same /mcp/ide/mcp URL is what the Claude pool puts in --mcp-config (AICliService._run_pooled_turn).
Bearer-token middleware (mcp_server.py:_BearerAuthMiddleware) validates each request against an in-memory per-batch BatchContext registry. Non-pool path: tokens registered at AICliService.run_batch() entry, unregistered in finally so 401s flip immediately when a batch settles. Pool path (use_pool=True, see Claude Code Interactive Mode for the full lifecycle): claude bakes the bearer into argv (--mcp-config) at spawn time and can't rotate without respawning, so the pool stashes the spawn-time token on PooledClaudeSession.batch_token and rebinds the BatchContext in place on warm reuse via rebind_batch(token, connected_tools=..., ...) — closes the "disconnected tool still works" leak by (a) diffing connected_tools and decrementing FastMCP refcounts for tools dropped between batches, and (b) updating the per-handler scope check's data so workflow_tools._build_handler returns 403 for stale tools. _terminate_locked calls unregister_batch(session.batch_token) so refcounts drain on pool eviction / clear / shutdown_all.
Tools exposed (mirror OpenCompany capabilities; deferred ones marked):
| Tool | Maps to | Returns |
|---|---|---|
mcp__opencompany__getWorkspaceFiles |
Path.rglob over workspace_dir |
{files: [{path, size, mtime, content?}]} |
mcp__opencompany__listSkills |
SkillLoader.scan_skills() filtered to BatchContext.connected_skill_names |
{skills: [{name, description, allowed_tools, category}]} (~100 tokens each) |
mcp__opencompany__getSkill |
skill_runtime.execute_skill_tool(action="load") for a skill in BatchContext.connected_skill_names |
Skill load result: instructions + resource manifest |
mcp__opencompany__readSkillResource |
execute_skill_tool(action="read_resource", path, cursor, limit=4000) |
Bounded page of a declared resource from a loaded skill |
mcp__opencompany__searchSkillResource |
execute_skill_tool(action="search_resource", path, query, cursor, limit=20) |
Line-numbered matches in a declared text resource |
mcp__opencompany__getCredential |
auth_service.get_api_key(name), gated by BatchContext.allowed_credentials |
{name, value} or 403 |
mcp__opencompany__broadcastLog |
broadcaster.broadcast_terminal_log() |
{success} |
Lifespan: main.py enters mcp_app.router.lifespan_context() so StreamableHTTPSessionManager's task group is alive (Starlette doesn't auto-propagate app.mount() lifespans). Stale-PID lockfile sweep on startup (mirrors VSCode's behaviour).
Files (current state)
Generic framework — server/services/cli_agent/
Shared by every CLI provider plugin. Imports nothing from nodes/.
| File | Purpose |
|---|---|
__init__.py |
Imports _handlers.py (codex WS handlers) + registers codex provider; framework-level self-registration only. Claude self-registers from its own plugin folder. |
protocol.py |
AICliProvider Protocol + CanonicalUsage / SessionResult / BatchResult dataclasses. |
types.py |
Pydantic discriminated-union task specs + BatchResultModel for serialisation. |
config.py |
Loads server/config/ai_cli_providers.json (binary, package, defaults, supports flags per provider). |
factory.py |
Three registries (register_provider, register_session_pool, register_skill_materialiser) + lookups + create_cli_provider(name). |
lockfile.py |
VSCode-style IDE lockfile read/write/sweep. |
mcp_server.py |
FastMCP sub-app mounted at /mcp/ide (JSON-RPC endpoint /mcp/ide/mcp) with bearer-token middleware + the infrastructure tools (getWorkspaceFiles, listSkills, getSkill, readSkillResource, searchSkillResource, getCredential, broadcastLog) + rebind_batch for warm-reuse context updates. |
context_bridge.py |
SpecializedAgentContextBridge — RFC-0002 Context continuity for specialized providers (resolve / augment_prompt / record_turn); shared with RLM. |
workflow_tools.py |
Per-batch MCP tool exposure (mcp__opencompany__<node_type>) + handler scope check + tools/list_changed notify. |
session.py |
AICliSession(BaseProcessSupervisor) — PTY + JSONL path. Not used for claude; run_batch uses it for a provider with no session pool (Codex), but _do_start raises for every provider except claude, so those runs fail. |
service.py |
AICliService.run_batch() — dispatcher; every claude task goes to the pool via factory.get_session_pool(provider_name) (warm keyed session when bound, ephemeral per-task session otherwise). |
_cli_auth.py |
CLI-agnostic mark_logged_in / mark_logged_out / broadcast_credential_event + "cli-managed" marker token. Shared by claude + codex handlers. |
_handlers.py |
Codex WS handlers (codex_cli_login / codex_cli_logout). Claude's moved to the plugin folder. |
providers/openai_codex.py |
Codex provider — sandbox-first, no session continuity. Will move when codex_agent adopts the per-folder layout. |
providers/google_gemini.py |
v2 stub. |
jsonl_watcher.py |
Used only by AICliSession; no claude caller. |
Claude plugin — server/nodes/agent/claude_code_agent/
Self-contained per the canonical plugin-folder pattern (telegram is
the reference implementation). Four self-registration calls in
__init__.py wire it into the framework — zero changes to
services/cli_agent/ when claude internals change.
| File | Purpose |
|---|---|
__init__.py |
ClaudeCodeAgentNode(ActionNode) + 4 self-registration calls: register_provider, register_session_pool, register_skill_materialiser, register_ws_handlers. |
_provider.py |
AnthropicClaudeProvider — full claude argv builder + stream-json event parsers + ide_lockfile_dir derivation. |
_pool.py |
ClaudeSessionPool — subprocess + stream-json warm-reuse pool, MCP rebind on acquire, skill diff on warm reuse. |
_skills.py |
materialise_skills(workspace_dir, names, previous_skill_names) — per-workflow SKILL.md materialisation + diff-based add/remove. |
_oauth.py |
OPENCOMPANY_CLAUDE_DIR, claude_binary_path, claude_auth_* — project-local install + the documented CLI subcommands. |
_handlers.py |
claude_code_login / claude_code_logout WS handlers (registered from __init__.py via register_ws_handlers). |
Other touchpoints
| File | Purpose |
|---|---|
server/config/ai_cli_providers.json |
Per-provider config (binary names, npm packages, login/auth_status argvs, supports flags). |
server/nodes/agent/codex_agent/__init__.py |
Codex node plugin — Params.tasks: list[CodexTaskSpec]. (Provider class still lives in services/cli_agent/providers/openai_codex.py until this folder adopts the per-folder layout.) |
server/nodes/visuals.json |
claude_code_agent + codex_agent icon/color entries. |
server/config/credential_providers.json |
_cli_base abstract + claude_code + codex_cli entries. |
server/services/workflow.py |
cancel_deployment calls get_ai_cli_service().cancel_workflow(workflow_id). |
server/main.py |
Mounts /mcp/ide sub-app, composes its lifespan, runs stale-lockfile sweep on startup. Side-effect imports services.cli_agent so its WS handlers self-register. Claude's plugin folder is discovered separately by the node registry. |
server/routers/websocket.py |
No CLI handlers inline — discovered via services.ws_handler_registry.get_ws_handlers(). |
Output contract
{
"tasks": [{
"task_id": "t_<8hex>",
"session_id": "<UUID|null>",
"provider": "claude|codex|gemini",
"prompt": "...",
"branch": "opencompany/t_<8hex>",
"worktree_path": "<abs path, removed after batch>",
"response": "<truncated to 4000 chars>",
"cost_usd": 0.42,
"duration_ms": 18234,
"num_turns": 7,
"tool_calls": 12,
"canonical_usage": {
"input_tokens": 5000, "output_tokens": 1000,
"cache_read": 500, "cache_write": 0,
"reasoning_tokens": 0, "request_count": 7
},
"provider_data": {
"reasoning_details": "...", // Claude only
"call_id": "...", // Codex only
"extra_content": [...] // Gemini only (v2)
},
"success": true, "error": null
}],
"summary": {
"n_tasks": 3, "n_succeeded": 2, "n_failed": 1,
"total_cost_usd": 1.23,
"wall_clock_ms": 19002
},
"provider": "claude|codex|gemini",
"timestamp": "2026-05-04T12:00:00Z"
}
cost_usd is the provider's reported value when available (Claude). For Codex (no native USD), service.py:_derive_cost falls back to services.pricing.PricingService.calculate_cost() from canonical_usage — single source of truth for LLM cost across OpenCompany. summary.total_cost_usd is null if any task didn't surface cost.
Memory bridge — simpleMemory → claude_code_agent
See memory_lifecycle.md for the shared markdown surface (every agent uses the same
parse_memory_markdown/append_to_memory_markdown/trim_markdown_windowhelpers to maintainsimpleMemory.memory_content). This section documents what's UNIQUE toclaude_code_agent: the markdown is the UI mirror, not the resume channel.
Connecting a simpleMemory node to a claude_code_agent makes the
spawned claude subprocess resume its prior session natively across runs.
No system-prompt injection, no JSONL synthesis, no API fallback.
Claude maintains its own session JSONL on disk under
<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl; we
just feed it the right argv and keep the cwd stable so the project
key doesn't drift.
Why native resume needs a stable cwd
Claude derives project_key from cwd via re.sub(r"[^a-zA-Z0-9-]", "-", str(cwd))
(_PROJECT_KEY_RE in session.py) — every :, \, /, _ and .
becomes -. An earlier version kept . and watched a directory the
CLI never wrote to (GitHub issue #132); the fix was checked against the
on-disk ~/.opencompany/claude/projects/ listing. The pre-bridge per-task
worktree (<workspace>/<node_id>/wt_t_<random_8hex>) changed cwd on
every spawn → fresh project_key every run → --resume <UUID> looked
under a brand-new directory with zero prior JSONL ("No conversation
found with session ID").
The fix: when memory is wired, spawn in one stable worktree per agent
node (<workspace>/<node>/wt_session) instead of a fresh per-task one.
Same cwd every run → same project_key → claude finds its own JSONL.
Pooled sessions never run in the repo root itself: claude reads
CLAUDE.md from cwd upward, and the checkout that contains DATA_DIR
would otherwise ride into every session.
Argv contract
| Run state | Argv emitted | Why |
|---|---|---|
| First cold spawn, no stored session | --session-id <uuid4> |
ClaudeSessionPool._spawn mints the UUID so it is known before the first event; _persist_memory stores it on the memory node as last_session_id. |
| Cold spawn under a memory-wired node with a stored session | --resume <last_session_id> |
Resume by UUID, never --continue: per code.claude.com/docs/en/cli-reference --continue skips sessions created non-interactively (-p / stream-json), which is every session the pool creates. |
| Subsequent turn, SAME warm subprocess | nothing argv-level — stream-json line on proc.stdin |
The pool keeps the subprocess alive between turns. Claude maintains the conversation in-process; same session_id across turns (verified end-to-end). |
| Crash recovery (subprocess died between batches) | --resume <captured_uuid> |
ClaudeSessionPool.acquire detects process.returncode is not None, captures the dead session's current_session_uuid, and respawns with --resume. Same cwd (the stable <workspace>/<node>/wt_session worktree) → same project_key → claude finds the same JSONL it was writing before the crash. Mutually exclusive with --continue. |
| Idle reap or LRU eviction | --session-id <new uuid4>, or --resume <last_session_id> when memory-bound |
The pool entry and its UUID are dropped. Memory-bound runs resume through the memory node; Context-bound runs start a fresh Claude session and keep only the rendered transcript (see claude_code_interactive_mode.md → Known gaps). |
Argv emission lives in
nodes/agent/claude_code_agent/_provider.py:interactive_argv.
The ClaudeTaskSpec carries continue_session: bool and
resume_session_id: Optional[str]. claude_code_agent.execute_op sets
resume_session_id from the memory node's last_session_id and leaves
continue_session at its False default (claude_code_agent/__init__.py); the
pool's crash-recovery path injects resume_session_id = session.current_session_uuid into the spec before respawning.
The pre-cutover UUID5 derivation is gone; the --session-id emitted today is
a fresh uuid4 minted by ClaudeSessionPool._spawn on cold start (claude
rejects a UUID already in use).
Plumbing
ClaudeCodeAgentNode.execute_op (claude_code_agent/__init__.py)
├─ collect_agent_connections() → context_data (first tuple element)
│ ├─ Context node wired: a Context descriptor (kind == "context") → context_descriptor,
│ │ handed to AICliService as connected_context and bridged through
│ │ SpecializedAgentContextBridge; memory_data stays None
│ └─ legacy input-memory graphs: the recorded Memory descriptor → memory_data
│ {node_id, session_id, memory_content, window_size,
│ long_term_enabled, last_session_id (read on every run)}
├─ resume_session_id = memory_data.get("last_session_id")
├─ ClaudeTaskSpec(..., resume_session_id=resume_session_id)
│ (a task from params.tasks gets it too, unless it set continue_session
│ or its own resume_session_id)
└─ AICliService.run_batch(..., connected_memory=memory_data,
broadcaster=...)
└─ For context/memory-wired single-task runs, route through ClaudeSessionPool
(run_batch: use_pool = the provider registered a session pool;
bound_key = context_bridge.pool_key, else connected_memory["node_id"],
else None. Unbound batches still run pooled, one ephemeral session per task.)
├─ pool.acquire(session_key, spec, cwd=<workspace>/<node>/wt_session, env, ...)
│ session_key = context_bridge.pool_key when a Context node is wired (the
│ RFC-0002 conversation key, so a Reset's generation bump
│ fences the warm subprocess), else the legacy
│ connected_memory["node_id"]
│ ├─ cold: spawn `claude --output-format stream-json
│ │ --input-format stream-json --verbose --ide
│ │ --session-id <uuid> | --resume <uuid> ...` as subprocess with stdio pipes;
│ │ no PTY. stdout_reader_task parses each event line
│ │ and dispatches to _handle_stream_event.
│ └─ warm reuse: return the existing PooledClaudeSession;
│ the next prompt rides the same subprocess.
│ └─ crash recovery: capture current_session_uuid from the
│ dead session, splice resume_session_id
│ onto the spec, spawn fresh with --resume.
├─ pool.send_turn(session, prompt):
│ ├─ write {"type":"user","message":{...}} + "\n" to proc.stdin
│ └─ await session.result_event (set by the stdout reader
│ when claude emits `result`)
├─ pool.release(session) ← marks idle for the reaper
└─ _persist_memory(connected_memory, results, broadcaster):
├─ append_memory_turns_atomic(db, memory_node_id, turns,
│ window_size=..., parameter_updates={"last_session_id": ...})
│ one write: appends the user/assistant turns to
│ params["memory_content"] and stores last_session_id, which the
│ next run reads for --resume
└─ broadcaster.broadcast_node_parameters_updated(
memory_node_id,
parameters=params,
source_hint="cli",
)
# Emits a CloudEvents v1.0 envelope (RFC §6.4):
# { type: "node_parameters_updated",
# data: { specversion, id, time,
# source: "opencompany://services/parameters",
# type: "com.opencompany.node.parameters.updated",
# subject: <memory_node_id>,
# workflow_id?,
# data: { node_id, parameters, version, source } } }
# The FE handler in `client/src/contexts/WebSocketContext.tsx`
# casts ``data`` to ``WorkflowEvent<{node_id, parameters,
# version, source}>`` and routes the inner payload to
# ``setNodeParameters`` + ``queryClient.setQueryData``,
# so the simpleMemory parameter panel auto-refreshes
# live (no page reload needed). Snake-case wire keys
# preserved (``node_id``, not ``nodeId``).
Parallel-batch guard
Memory continuity requires serial execution — N concurrent --resume
spawns against the same session would race claude's transcript
writes. When memory_data is wired AND len(tasks) > 1,
claude_code_agent raises NodeUserError("Memory-bound batches must run one task at a time. ...") at handler entry.
Markdown mirror
memory_content (the markdown surface the simpleMemory UI shows) is
a display mirror, not the resume channel. Claude's own JSONL on
disk is what --resume loads from; last_session_id on the memory
node is the resume handle. _persist_memory
appends each successful run's prompt + response to memory_content
via append_memory_turns_atomic so the UI shows the conversation grow
live. User edits to memory_content do NOT influence claude's next
response.
To reset both: click the simpleMemory's clear button or invoke the
clear_memory WS handler — backend wipes memory_content to the
default placeholder AND clears last_session_id in one DB write.
Claude's on-disk JSONL is left alone (orphan, harmless). The next run
has no last_session_id, so the pool mints a new --session-id and
claude starts a brand-new session.
Logs to watch
[Claude Code memory] memory_node=<id> -> --resume <UUID>
(or "fresh session (no last_session_id yet)" on the first run)
[CC-Agent run_batch] enter ... memory=<memory_node_id> ...
[ClaudeSessionPool] spawned new session memory_node=<id> pid=<N>
(cold spawn — argv carries --session-id <UUID> or --resume <UUID>)
[ClaudeSessionPool] warm reuse memory_node=<id> pid=<N> uuid=<UUID>
(intra-process turn — stream-json on stdin)
[CC-Agent _persist_memory] saved memory_node=<id> last_session_id=<UUID>
appended_turns=1 archived_blocks=0 content_length=<N>
On a crash-recovery path the trace shows:
[ClaudeSessionPool] dropping dead session memory_node=<id>
pid=<dead-pid> exit=<code> — will respawn
[ClaudeSessionPool] spawned new session memory_node=<id> pid=<new-pid>
(argv: --resume <UUID> taken from the dead session's
current_session_uuid; same project_key, same JSONL continues)
Status broadcast events
| Phase | When | Payload |
|---|---|---|
batch_started |
run_batch entry |
{provider, n_tasks, max_parallel, isolation:"worktree"} |
ai_cli_subtask |
per-task partial (NDJSON event); AICliSession only |
{task_id, provider, status:"running", message, cost_usd?, num_turns?} |
ai_cli_subtask |
per-task final; AICliSession only |
`{task_id, provider, status:"succeeded" |
batch_complete |
aggregator finish | {provider, n_succeeded, n_failed, total_cost_usd?, wall_clock_ms} |
AICliSession also calls broadcast_terminal_log(source=f"{provider}:{task_id}", level) on every event line for the Terminal tab. The Claude pool emits neither ai_cli_subtask nor terminal-log lines: a Claude run surfaces through batch_started / batch_complete, the node status the plugin sets, and the claude.session.* CloudEvents (see claude_code_interactive_mode.md).
Plugin contract — adding a new CLI provider
To add a fourth provider (e.g. Mistral CLI) post-v1:
- New plugin folder
server/nodes/agent/<vendor>_agent/rooted at__init__.py(mirrornodes/agent/claude_code_agent/;codex_agent/is the smaller example whose provider class still lives underservices/cli_agent/providers/). Put the provider (_provider.py, implementingAICliProvider), any pool, and the WS handlers (_handlers.py, login + logout) in that folder. - New entry in
server/config/ai_cli_providers.json. - New
<vendor>TaskSpecintypes.py+ register in the discriminated union. - Call
register_provider("<vendor>", <ProviderClass>)(andregister_session_pool/register_skill_materialiserif applicable) from the plugin's__init__.py— there is no branch to add infactory.create_cli_provider; it is a registry lookup. - New entry in
server/config/credential_providers.json(extends: "_cli_base"). register_ws_handlers({...})from the plugin's__init__.pyfor the login/logout handlers.meta.json(+icon.svg) in the plugin folder, or aserver/nodes/visuals.jsonentry as the legacy fallback.
No edits to routers/websocket.py, main.py, services/cli_agent/, or any existing handler/service. The plugin auto-registers via BaseNode.__init_subclass__ (Wave 11) + the services.ws_handler_registry self-registration from its own __init__.py.
Verification
Unit tests (in server/tests/services/cli_agent/):
test_providers.py— Claude + Codex argv shapes, parse_event fidelity (vendored NDJSON), event_to_session_result reconstruction, auth-error detection,supports()flags. Factory raisesNotImplementedErrorforgemini.test_mcp_server.py— bearer-token registry register/lookup/unregister, 401 on missing/malformed/unknown/expired tokens, lockfile shape matches VSCode convention, stale-PID sweep.test_service.py—not_git_repoabort path, resolver contract (explicitrepo_rootdoesn't fall back to cwd), cancel-when-idle, singleton.
Plugin contract: tests/test_plugin_contract.py + tests/test_node_spec.py — clean per-provider Params schemas, no $defs/$ref in the fast-path.
Live verification (needs a real Claude install + auth):
- Empty
~/.opencompany/claude/+~/.opencompany/packages/. Open Credentials Modal → click "Login with Claude Code CLI". Confirm thebun addruns (visible in backend logs),~/.opencompany/packages/node_modules/.bin/claude[.exe]appears, browser opens for Anthropic OAuth. Modal flips Connected within ~2s of CLI exit (backgroundclaude auth statuspoll detects success). The browser tab should render the CLI's own "Signed in" success page (this needs thestdin=PIPEspawn — without it the native binary exits early and the tab is left on the barelocalhost/callbackURL). - Refresh the page. Modal stays Connected (
auth_service.get_oauth_tokens("claude_code")still returns the marker; idempotent re-click also stays Connected). - Click Disconnect. Modal flips Disconnected (
claude auth logoutclears CLI creds + marker dropped). - Add a
claude_code_agentnode, settasks=[{prompt:"echo A"},{prompt:"echo B"},{prompt:"echo C"}], run. Three distinct session_ids. Threewt_<run>_<i>worktrees created and removed.summary.wall_clock_ms < sum(duration_ms)(proves parallelism). - With a Claude task running that calls a wired tool, the backend log shows
[CC-Agent MCP auth] POST ... -> OK (node=... wf=... token=...)for MCP requests carrying the--mcp-configbearer, and the task result'stool_callsis non-zero. No IDE lockfile is written. curl -H "Authorization: Bearer <wrong>" http://127.0.0.1:${PYTHON_BACKEND_PORT}/mcp/ide/mcp→ 401.
Risks / open considerations
- Codex login not yet wired. v1 returns a graceful error directing the user to
bun add -g @openai/codex+codex login. Follow-up: a codex_oauth.pymirroringnodes/agent/claude_code_agent/_oauth.pywith aHOME=<DATA_DIR>/codex/env redirect (Codex has noCONFIG_DIRenv;HOMEredirect is risky on Windows, so Windows may need a different strategy or accept user-global Codex auth). - Gemini deferred.
factory.create_cli_provider("gemini")raisesNotImplementedError(the one name-specific branch left in the factory, kept so the dropdown can grey it out). v2 work: implement the provider, register it from anodes/agent/gemini_cli_agent/plugin folder, and drop that branch. ~430 LoC. No abstraction changes needed. - Codex fails on every run. No session pool is registered for Codex, so
run_batchruns it throughAICliSession, andAICliSession._do_startraises for every provider exceptclaude. The task comes back failed withworktree_setup_failed: AICliSession (interactive PTY+JSONL) currently only supports the 'claude' provider ...(orcli_not_installedwhen the Codex binary is missing). A Codex session class or pool is needed before the node can work. - Claude pool gaps. Context-bound runs lose Claude's own session after a reap or eviction, the stored transcript is re-sent on every warm turn, the spawn inherits the backend's environment while passing
--ide,getCredential/broadcastLogare model-visible, and warm reuse keeps the spawn-time flags and skill descriptors. Details in claude_code_interactive_mode.md → Known gaps. - Native-binary stdin sensitivity. claude-code >= 2.1.162 ships a native binary that reads stdin during
auth login. We spawn it withstdin=asyncio.subprocess.PIPE(never written) so the read blocks and the OAuth callback server stays alive; an inherited/closed stdin EOFs the binary into an early exit that drops the browser callback. If a future CLI version changes its stdin contract this is the spot to revisit. - Marker token written without verifying CLI is actually functional — we trust
claude auth status's exit code. If Anthropic invalidates the token server-side and the CLI hasn't re-checked, the modal still shows Connected until the next session attempt'sdetect_auth_errorcatches it. - MCP SDK is pre-1.0-stable. Pinned at
mcp>=1.0.0. The surface is isolated inmcp_server.pyso an SDK breaking change touches one file. - Concurrent install safety.
_oauth.py:claude_binary_pathdoesn't currently use a lock — two simultaneous login clicks within 2s could race thebun addinto the shared tree. Low-risk in practice (modal debounces clicks); a follow-up could add anasyncio.Lock. - Worktree leak on hard crash. Out-of-scope cleanup pass; document.