Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(claude-code): update OpenCompany notes in the CLI snapshots
trohitg16670839da74
diff --git a/docs-internal/claude_code_cli_reference.md b/docs-internal/claude_code_cli_reference.mdindex ea27ac5a..a5effcf2 100644--- a/docs-internal/claude_code_cli_reference.md+++ b/docs-internal/claude_code_cli_reference.md@@ -187,16 +187,16 @@ Quick cross-reference for the OpenCompany `claude_code_agent` integration:| `--output-format stream-json` | always | NDJSON event stream consumed by `_pool.py` || `--input-format stream-json` | always | prompts are written to the long-lived subprocess over stdin || `--verbose` | always | include complete stream-json event detail |-| `--ide` | always | discover the per-process IDE lockfile used for MCP connectivity |+| `--ide` | always | matches the VSCode extension's argv; OpenCompany writes no IDE lockfile and sets no `CLAUDE_IDE_LOCK`, so the MCP connection comes only from `--mcp-config` || `--model <id>` | always | from `ClaudeTaskSpec.model` / config default |-| `--permission-mode <mode>` | normally | defaults to `dontAsk` so the explicit allowlist remains authoritative without interactive prompts |-| `--allowedTools <csv>` | always | connected workflow tools plus OpenCompany MCP infrastructure tools; Claude built-ins are opt-in, except `Skill` when a skill is connected |+| `--permission-mode <mode>` | normally | defaults to `dontAsk`: a call that is not pre-approved is denied instead of prompting (read-only Bash commands still run) |+| `--allowedTools <csv>` | always | pre-approves connected workflow tools plus OpenCompany MCP infrastructure tools; Claude built-ins are opt-in, except `Skill` when a skill is connected. Pre-approval only: per the table above it does not restrict which tools the model sees (that is `--tools`, not emitted) || `--mcp-config <json>` | when MCP wired | inline JSON with `{mcpServers: {opencompany: {type: http, url, headers, alwaysLoad: true}}}` || `--strict-mcp-config` | when MCP wired | blocks user-level `~/.claude.json` MCP entries || `--append-system-prompt <text>` | when `system_prompt` is set | append the task prompt to Claude Code's built-in system prompt || `--session-id <UUID>` | cold spawn with no continuity flag | host-minted `uuid4` so the session UUID is known before the first event (must be a valid UUID; rejected if already in use) |-| `--resume <UUID>` | memory-bound runs (`last_session_id` from the memory node) and pooled-process crash or reap recovery | resume by UUID; works from any directory since 2.1.223 |-| `--continue` | never set by the node | the reference says it skips sessions created non-interactively (`-p` / stream-json), i.e. every session the pool creates; kept on `ClaudeTaskSpec` for explicit callers only |+| `--resume <UUID>` | memory-bound runs (`last_session_id` from the memory node) and pooled-process crash recovery | resume by UUID; works from any directory since 2.1.223. An idle reap or LRU eviction drops the pool entry and its UUID, so it is not resumed from the pool |+| `--continue` | not set by the node's continuity logic; emitted when a task sets `continue_session: true` | the reference says it skips sessions created non-interactively (`-p` / stream-json), i.e. every session the pool creates || `--effort <level>` | optional per-task override | reasoning effort || `--add-dir <path>*` | optional per-task override | grant extra working dirs || `--disallowedTools <csv>` | optional per-task override | remove tools from context |diff --git a/docs-internal/claude_code_env_vars_reference.md b/docs-internal/claude_code_env_vars_reference.mdindex c13377f4..94509fbe 100644--- a/docs-internal/claude_code_env_vars_reference.md+++ b/docs-internal/claude_code_env_vars_reference.md@@ -119,7 +119,7 @@ sets or relies on.| Variable | Purpose ||---|---|-| `CLAUDE_CONFIG_DIR` | Override the root config directory. Defaults to `~/.claude/`. **OpenCompany sets this** to `<DATA_DIR>/claude/` (= `~/.opencompany/claude/` by default) so credentials are project-local and isolated from the user's own `~/.claude/` session — see `nodes/agent/claude_code_agent/_oauth.py:OPENCOMPANY_CLAUDE_DIR` (`= data_path("claude")`). This is the directory under which claude's session JSONL lives at `<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl`. The npm-installed CLI binary is separate, in the shared tree at `<DATA_DIR>/packages/node_modules/.bin/claude[.cmd]`. |+| `CLAUDE_CONFIG_DIR` | Override the root config directory. Defaults to `~/.claude/`. **OpenCompany sets this** to `<DATA_DIR>/claude/` (= `~/.opencompany/claude/` by default) so credentials are project-local and isolated from the user's own `~/.claude/` session — see `nodes/agent/claude_code_agent/_oauth.py:OPENCOMPANY_CLAUDE_DIR` (`= data_path("claude")`). This is the directory under which claude's session JSONL lives at `<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl`. The CLI itself is separate: `bun add`ed into the shared tree, with its shim at `<DATA_DIR>/packages/node_modules/.bin/claude` (`claude.exe` on Windows). || `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | Default prefix for auto-generated Remote Control session names. |## Timeouts@@ -139,11 +139,20 @@ sets or relies on.## Env vars OpenCompany explicitly sets on the spawn env-From [`services/cli_agent/session.py:env()`](../server/services/cli_agent/session.py):+For Claude, the pooled spawn env is built in `AICliService._run_pooled_turn`+([`services/cli_agent/service.py`](../server/services/cli_agent/service.py)).+It starts from the backend's whole `os.environ`, removes nothing, and adds:| Variable | Set to | Reason ||---|---|---|| `PYTHONUNBUFFERED` | `1` | Line-buffered output (we parse stream-json line by line). |-| `CLAUDE_CONFIG_DIR` | `OPENCOMPANY_CLAUDE_DIR` (claude provider only) | Project-local credential isolation; also where claude writes its session JSONL — load-bearing for the memory bridge (`<key>/projects/<cwd-encoded>/<session_id>.jsonl`). |-| `<provider.ide_lock_env_var>` | path to per-spawn lockfile | VSCode-style IDE auto-discovery. |-| `OPENCOMPANY_PARENT_RUN_ID` | `<workflow_id>:<node_id>:<batch_token[:8]>` | Composio-style parent-run-id for MCP correlation. |+| `CLAUDE_CONFIG_DIR` | `OPENCOMPANY_CLAUDE_DIR` | Project-local credential isolation; also where claude writes its session JSONL — load-bearing for the memory bridge (`<key>/projects/<cwd-encoded>/<session_id>.jsonl`). |+| `OPENCOMPANY_PARENT_RUN_ID` (and the legacy `MACHINA_PARENT_RUN_ID`) | `<workflow_id>:<session_key>:<batch_token[:8]>` | Composio-style parent-run-id for MCP correlation. |++No IDE-lock variable is set on this path. The generic `AICliSession.env()`+in [`services/cli_agent/session.py`](../server/services/cli_agent/session.py)+(not used for Claude) also sets `<provider.ide_lock_env_var>` to the+lockfile it wrote. Because the whole backend environment is inherited,+variables from the shell that started the backend (an editor's+IDE-integration variables, for example) reach the CLI; see+[claude_code_interactive_mode.md → Known gaps](./claude_code_interactive_mode.md#known-gaps).diff --git a/docs-internal/claude_code_headless_reference.md b/docs-internal/claude_code_headless_reference.mdindex 8925bf11..183fd227 100644--- a/docs-internal/claude_code_headless_reference.md+++ b/docs-internal/claude_code_headless_reference.md@@ -2,12 +2,14 @@> **Source:** [code.claude.com/docs/en/headless](https://code.claude.com/docs/en/headless)> **Fetched:** 2026-05-11-> **Why this lives in-repo:** OpenCompany spawns `claude -p` via-> `services/cli_agent/`. The argv flags this doc describes-> (`--output-format stream-json`, `--include-partial-messages`,-> `--include-hook-events`, `--max-budget-usd`, `--max-turns`,-> `--bare`) and the stream-json event schema it documents are-> load-bearing for our session parser.+> **Why this lives in-repo:** OpenCompany no longer spawns `claude -p`.+> `ClaudeSessionPool` runs `claude --output-format stream-json+> --input-format stream-json --verbose --ide ...` over stdio pipes (see+> [claude_code_interactive_mode.md](./claude_code_interactive_mode.md)).+> The stream-json event schema this doc documents is still the contract+> the pool parses; the print-mode-only flags it describes+> (`--include-partial-messages`, `--max-budget-usd`, `--max-turns`) are+> not emitted.---@@ -265,27 +267,27 @@ claude -p "Continue that review" --resume "$session_id"## What OpenCompany reads from this stream-`services/cli_agent/session.py:_consume_stdout` parses every line of-`--output-format stream-json` output. The event types we touch:+The stdout reader started in `ClaudeSessionPool._spawn`+([`nodes/agent/claude_code_agent/_pool.py`](../server/nodes/agent/claude_code_agent/_pool.py))+parses every line of `--output-format stream-json` output and hands it to+`_handle_stream_event`:| Event | What we do with it ||---|---|-| `type: "system"` `subtype: "init"` | Log tools count + mcp_servers list. First evidence the spawn is healthy. |-| `type: "assistant"` `content: [text]` | Log a 300-char preview as `[CC-Agent stream] assistant.text`. |-| `type: "assistant"` `content: [tool_use]` | Log tool name + input keys as `assistant->tool_use`. |-| `type: "tool_use"` (top-level) | Log name + input keys. |-| `type: "tool_result"` | Log `is_error` + 300-char content preview. |-| `type: "hook"` | Log hook event name (requires `--include-hook-events`). |-| `type: "result"` | Final summary — drives `SessionResult` (`session_id`, `total_cost_usd`, `duration_ms`, `num_turns`, `usage`). |--`--include-partial-messages` surfaces deltas to the Terminal panel via-`broadcast_terminal_log`; we don't aggregate them into messages-because the `result` event carries the final response anyway.--`--max-budget-usd` is set from `ClaudeTaskSpec.max_budget_usd` (default-`5.0` USD) so we cap per-task spend.--`--max-turns` is set from `ClaudeTaskSpec.max_turns` (default `10`).+| any event with `session_id` | Seeds the pooled session's UUID if it is still empty (a `--continue` spawn; otherwise the UUID is known from `--session-id` / `--resume`). |+| every event | Appended to the turn's event buffer, which `AnthropicClaudeProvider.event_to_session_result` turns into the `SessionResult`. |+| `type: "result"` | Ends the turn — drives `SessionResult` (`session_id`, `total_cost_usd`, `duration_ms`, `num_turns`, `usage`) and the `claude.session.usage` CloudEvent. |+| `type: "system"` `subtype: "compact_boundary"` | Forwarded to `CompactionService.record(...)`. |++The per-event log previews (`assistant.text`, tool calls, tool results)+and Terminal-panel lines are produced only by the generic+`AICliSession` (`services/cli_agent/session.py`), which Claude no+longer uses.++`--include-partial-messages`, `--max-budget-usd` and `--max-turns` are+not emitted: they are print-mode only. `ClaudeTaskSpec` keeps+`max_budget_usd` and `max_turns` for back-compat, but nothing caps+per-task spend or turns today.We do NOT use `--bare` — auto-discovery of hooks/skills/MCP/auto-memoryis what makes the workflow-tool bridge work. CI use cases that wantdiff --git a/docs-internal/claude_code_permission_modes_reference.md b/docs-internal/claude_code_permission_modes_reference.mdindex e4d83ccd..e8d6b1fe 100644--- a/docs-internal/claude_code_permission_modes_reference.md+++ b/docs-internal/claude_code_permission_modes_reference.md@@ -3,7 +3,8 @@> **Source:** [code.claude.com/docs/en/permission-modes](https://code.claude.com/docs/en/permission-modes)> **Fetched:** 2026-05-11> **Why this lives in-repo:** OpenCompany's claude_code_agent defaults to-> `--permission-mode acceptEdits` and exposes the full enum+> `--permission-mode dontAsk` (`default_permission_mode` in+> `server/config/ai_cli_providers.json`) and exposes the full enum> (`default`, `acceptEdits`, `plan`, `auto`, `dontAsk`,> `bypassPermissions`) on `ClaudeTaskSpec.permission_mode`. See> `services/cli_agent/types.py` and@@ -283,8 +284,8 @@ Writes to a small set of paths are never auto-approved, in every mode except `by| Mode | Where | Notes ||---|---|---|-| `acceptEdits` | Default on `ClaudeTaskSpec.permission_mode` | Auto-approves file edits + safe filesystem commands inside cwd. cwd is `repo_root` for memory-bound runs (so claude can edit the actual repo) and the per-task worktree otherwise (isolated). |+| `dontAsk` | Default (`ClaudeTaskSpec.permission_mode` and `default_permission_mode` in `ai_cli_providers.json`) | No prompts. Pre-approval comes from the `--allowedTools` list `interactive_argv` builds; anything else is denied, except read-only Bash commands (see "Allow only pre-approved tools with `dontAsk` mode" above). The other built-ins stay visible to the model. |+| `acceptEdits` | User-selectable per task | Auto-approves file edits + safe filesystem commands inside cwd. cwd is a git worktree under the workflow workspace (`<workspace>/<node>/wt_session` for bound runs), never the repo root. Prompts for anything else, which hangs a headless run. || `plan` | User-selectable per task | When the user wants research without edits. || `bypassPermissions` | Available but not default | For sandboxed CI scenarios. Not recommended on a user's real repo. |-| `dontAsk` | Available but not default | For locked-down CI; agent must have `permissions.allow` rules pre-configured. || `auto` | Available but not default | Requires Sonnet 4.6 / Opus 4.6+ and Anthropic API plan; classifier model + token cost overhead. |diff --git a/docs-internal/claude_code_skills_reference.md b/docs-internal/claude_code_skills_reference.mdindex 637acff4..38fc4d44 100644--- a/docs-internal/claude_code_skills_reference.md+++ b/docs-internal/claude_code_skills_reference.md@@ -3,9 +3,10 @@> **Source:** [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills)> **Fetched:** 2026-05-11> **Why this lives in-repo:** OpenCompany materialises connected skills-> into `<cwd>/.claude/skills/<name>/SKILL.md` on `_pre_spawn` so claude-> auto-discovers them — see [`cli_agent_framework.md` → Memory bridge](./cli_agent_framework.md#memory-bridge--simplememory--claude_code_agent)-> and [`cli_agent_canonical_patterns_rfc.md` §5 R1](./cli_agent_canonical_patterns_rfc.md).+> into `<workspace_dir>/.claude/skills/<name>/SKILL.md` before the pool+> spawns claude, and claude finds them through `--add-dir <workspace_dir>`+> — see [`claude_code_interactive_mode.md` → Tools and skills](./claude_code_interactive_mode.md#tools-and-skills)+> and [`cli_agent_canonical_patterns_rfc.md` §6 R1](./cli_agent_canonical_patterns_rfc.md).> This is the spec we materialise against.---@@ -229,21 +230,29 @@ To raise the budget, set the `skillListingBudgetFraction` setting (e.g. `0.02` =## How OpenCompany materialises skills for `claude_code_agent`-[`services/cli_agent/session.py:_materialise_skills`](../server/services/cli_agent/session.py)+`materialise_skills` in+[`nodes/agent/claude_code_agent/_skills.py`](../server/nodes/agent/claude_code_agent/_skills.py)walks `connected_skill_names` (collected by edge_walker from theagent's `input-skill` handle) and writes each connected skill to-`<cwd>/.claude/skills/<name>/SKILL.md`:+`<workspace_dir>/.claude/skills/<name>/SKILL.md`, where+`<workspace_dir>` is the workflow's workspace, passed to claude with+`--add-dir`. `ClaudeSessionPool._spawn` calls it before a cold spawn and+`_prepare_warm_reuse` calls it on every warm reuse with the previous+set, so only the difference is written or removed:- **Filesystem-origin skills:** `shutil.copytree(skill.metadata.path, dest, dirs_exist_ok=True)` — preserves `SKILL.md` + supporting `scripts/`, `references/`, `templates/`, etc.- **DB-origin user skills:** synthesise the `SKILL.md` from `Skill.metadata` (`name`, `description`, `allowed-tools`, `metadata`) + `Skill.instructions` (the body) using `yaml.safe_dump` for the frontmatter.-For memory-bound runs (`memory_bound=True`), cwd is `repo_root`, so-skills land at `<repo_root>/.claude/skills/<name>/`. For non-memory-runs the cwd is the per-task worktree.+The cwd is a git worktree under the workspace (`<workspace>/<node>/wt_session`+for bound runs, one per task otherwise), never the repo root, so+skills never land in the user's repository.Per *Live change detection* above, claude picks the skills up-mid-session without a restart — but our spawn is fresh each task-anyway, so we don't rely on that.+mid-session without a restart. The pool relies on that: a warm process+is reused across runs, and the warm-reuse diff adds or removes skill+folders under it. (Whether the `Skill` tool itself is pre-approved is+fixed at spawn; see+[claude_code_interactive_mode.md → Known gaps](./claude_code_interactive_mode.md#known-gaps).)`allowed-tools` in OpenCompany-shipped SKILL.md files uses the samesyntax as upstream (`Bash(git diff *) Read` etc.) and is honoured by