Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Showing 1 changed file with 142 additions and 3 deletions.
| @@ -55,7 +55,13 @@ would break your Claude Code login. | ||
| 55 | 55 | Useful flags: `-model`, `-effort low|medium|high|xhigh|max`, `-max-turns`, |
| 56 | 56 | `-resume latest`, `-no-stream`, `-no-cache`, `-no-auto-compact`, `-v`, `-yolo`, |
| 57 | 57 | `-no-tui`, `-no-skills`, `-no-agents`, `-no-web`, `-no-hooks`, |
| 58 | - `-no-diagnostics`, `-no-mcp`, `-no-claude-code-auth`. | |
| 58 | + `-no-diagnostics`, `-no-mcp`, `-no-claude-code-auth`. And the ones a script | |
| 59 | + written for Claude Code passes, with Claude Code's meaning — see [using it in | |
| 60 | + place of `claude`](#using-it-in-place-of-claude): `--output-format | |
| 61 | + text|json|stream-json`, `-c`/`--continue`, `--allowedTools`, | |
| 62 | + `--disallowedTools`, `--permission-mode`, `--dangerously-skip-permissions`, | |
| 63 | + `--append-system-prompt`, `--system-prompt`, `--verbose`, `--print`. Every flag | |
| 64 | + takes one dash or two. | |
| 59 | 65 | |
| 60 | 66 | ### Flags and thresholds |
| 61 | 67 | |
| @@ -1340,6 +1346,135 @@ the only one where pressing enter through the screens does something: the row | ||
| 1340 | 1346 | names the exact path before you answer, and the notice afterwards names the |
| 1341 | 1347 | file that was written. Uninstalling is `rm -r ~/.agents/skills/herdr`. |
| 1342 | 1348 | |
| 1349 | + ## Using it in place of `claude` | |
| 1350 | + | |
| 1351 | + A lot of CI jobs and shell scripts run an agent as `claude -p`. Codey reads the | |
| 1352 | + same flags with the same meaning, so pointing one of them at Codey is meant to | |
| 1353 | + be a matter of changing the binary's name: | |
| 1354 | + | |
| 1355 | + ```bash | |
| 1356 | + codey -p --output-format json "why does TestFoo fail?" | jq -r .result | |
| 1357 | + echo "summarise the last commit" | codey -p --allowedTools "Bash(git log:*)" "Bash(git show:*)" | |
| 1358 | + codey -c -p "now fix it" # same session | |
| 1359 | + ``` | |
| 1360 | + | |
| 1361 | + | Claude Code flag | In Codey | | |
| 1362 | + | --- | --- | | |
| 1363 | + | `-p`, `--print` | One prompt, then exit. The prompt may follow `-p` — Codey's own spelling — or be a positional argument anywhere on the line, as `claude` takes it, or arrive on stdin when there is no other | | |
| 1364 | + | `--output-format text` | The final answer and nothing else on stdout | | |
| 1365 | + | `--output-format json` | One result object at the end | | |
| 1366 | + | `--output-format stream-json` | One JSON line per message as the run goes, then the result object | | |
| 1367 | + | `--verbose` | The same as `-v`. With `json` it prints every line `stream-json` would have, as one array, which is what Claude Code does; `stream-json` does not need it | | |
| 1368 | + | `-c`, `--continue` | `-resume latest`: the most recent session in this working root | | |
| 1369 | + | `--resume <id>` | Unchanged; the id is a Codey session id, which is what `session_id` in the output holds | | |
| 1370 | + | `--model`, `--max-turns` | Codey's own flags, already spelled the same | | |
| 1371 | + | `--allowedTools`, `--allowed-tools` | Calls to approve without asking, as rules | | |
| 1372 | + | `--disallowedTools`, `--disallowed-tools` | Tools to take away, or calls to refuse, as rules | | |
| 1373 | + | `--permission-mode` | `default`; `acceptEdits`, which lets edits and writes through and still asks before a command — the mode the ACP front end has by the same name; `bypassPermissions`, which is `-yolo`; `dontAsk`, which refuses whatever no rule allows | | |
| 1374 | + | `--dangerously-skip-permissions` | `-yolo` | | |
| 1375 | + | `--append-system-prompt`, `--system-prompt` | Add to the end of Codey's system prompt, or replace it. The session's own agent only: a subagent's prompt is its preset's | | |
| 1376 | + | `--include-partial-messages` | Accepted, with a warning, and ignored | | |
| 1377 | + | |
| 1378 | + Without `--output-format`, `-p` prints what it always has: the transcript as it | |
| 1379 | + streams, the tool calls, a usage line — for a person watching, not a parser. | |
| 1380 | + Asking for a format is asking for Claude Code's behaviour, and then stdout holds | |
| 1381 | + the format and nothing else; notices, warnings and any approval prompt go to | |
| 1382 | + stderr. | |
| 1383 | + | |
| 1384 | + The shapes are Claude Code's, because the programs reading them were written | |
| 1385 | + against it. The result object carries `type`, `subtype` (`success`, | |
| 1386 | + `error_max_turns` or `error_during_execution`), `is_error`, `result`, | |
| 1387 | + `session_id`, `num_turns`, `duration_ms`, `duration_api_ms`, `total_cost_usd` | |
| 1388 | + and `usage` with the four token counts. In `stream-json` it is preceded by a | |
| 1389 | + `system`/`init` line — working directory, model, tools, MCP servers, permission | |
| 1390 | + mode — then an `assistant` line per response, holding the message as the | |
| 1391 | + Messages API returned it, and a `user` line per batch of tool results. Numbers | |
| 1392 | + are this invocation's: a resumed session reports what the resume cost, not | |
| 1393 | + everything before it. | |
| 1394 | + | |
| 1395 | + A run that fails exits 1, whatever the format, and the JSON formats still print | |
| 1396 | + their result object — with `is_error: true`, the error in `errors`, and in | |
| 1397 | + `result` whatever the model last said, or the error itself when it said | |
| 1398 | + nothing. That includes failing before the model was ever asked: no credentials | |
| 1399 | + gives a result object, with an empty `session_id` because there was no session | |
| 1400 | + yet. Check `is_error` rather than `subtype`: it is the field that means | |
| 1401 | + failure in both, where the subtypes for a failure are not guaranteed to agree | |
| 1402 | + between the two. A flag | |
| 1403 | + Codey does not know stops the run before any of this, with exit 2, and so does | |
| 1404 | + a value it cannot use — `--permission-mode plan`, say — with exit 1 and a | |
| 1405 | + message on stderr. | |
| 1406 | + | |
| 1407 | + **Who gets asked.** Claude Code never prompts in `-p` mode, and with | |
| 1408 | + `--output-format` neither does Codey when stdin is not a terminal: what no rule | |
| 1409 | + allows is refused, and the model is told so and carries on. That is the case in | |
| 1410 | + CI. At a terminal the prompt still comes up, on stderr. Codey's own `-p` | |
| 1411 | + without a format keeps reading answers from stdin, so `yes | codey -p ...` | |
| 1412 | + works as it always has — except when the prompt itself came from stdin, which | |
| 1413 | + leaves nothing there to answer with. | |
| 1414 | + | |
| 1415 | + **Rules.** `--allowedTools` and `--disallowedTools` take Claude Code's rule | |
| 1416 | + syntax, comma- or space-separated, as many as you like after one flag: | |
| 1417 | + `Bash`, `Bash(git status)`, `Bash(npm run test:*)`, `Read`, `Read(./src/**)`, | |
| 1418 | + `Edit(./docs/**)`, `Write`, `Glob`, `Grep`, `WebFetch(domain:example.com)`, | |
| 1419 | + `WebSearch`, `TodoWrite`, `Task`, `mcp__github`, `mcp__github__create_issue`. | |
| 1420 | + Claude Code's names map onto Codey's tools — `Bash` is `bash`, `Read` | |
| 1421 | + `read_file`, `Write` `write_file`, and `Edit` both `edit_file` and | |
| 1422 | + `write_file`, because Claude Code applies its Edit rules to every tool that | |
| 1423 | + edits files. Codey's own names work as well. A rule naming a tool Codey does | |
| 1424 | + not have, `NotebookEdit` say, is a warning, and the rest of the list still | |
| 1425 | + applies. | |
| 1426 | + | |
| 1427 | + A rule for a whole tool on the disallowed list takes the tool away: the model | |
| 1428 | + is never shown it. A narrower one — `Bash(git push:*)`, `Read(./.env)` — is | |
| 1429 | + checked at approval time, before anything else, `-yolo` included, and a call it | |
| 1430 | + matches is refused. On the allowed list a rule stands in for the "yes" you | |
| 1431 | + would otherwise have been asked for. | |
| 1432 | + | |
| 1433 | + `Bash(prefix:*)` matches word by word, so `Bash(ls:*)` covers `ls -la` and not | |
| 1434 | + `lsof`. A compound command is allowed only when every simple command in it is | |
| 1435 | + covered, so `git status; rm -rf ~` does not ride in on `Bash(git status:*)`, and | |
| 1436 | + anything the [shell analysis](#safety) cannot see through — command | |
| 1437 | + substitution, a variable in command position, an inline `bash -c` script, an | |
| 1438 | + assignment like `PATH=...`, output redirected into a file — is never allowed by | |
| 1439 | + a narrower rule than `Bash`. A deny rule is the other way round: one matching | |
| 1440 | + part is enough, and it looks inside `bash -c` and `eval`, past `sudo`, `env` | |
| 1441 | + and `timeout`, and at `/bin/rm` as `rm`. That catches the command a model | |
| 1442 | + would ordinarily write. It is not a sandbox, for the reason the Safety section | |
| 1443 | + gives. | |
| 1444 | + | |
| 1445 | + Path rules read like gitignore, as Claude Code's do: `./` and `/` are the | |
| 1446 | + working root, `//` an absolute path, `~/` your home, and a pattern with no | |
| 1447 | + slash in it — `.env`, `*.pem` — matches a name at any depth. Path rules on | |
| 1448 | + `Read` apply to `glob` and `grep` too, as far as their `path` argument goes. | |
| 1449 | + | |
| 1450 | + What does not work: | |
| 1451 | + | |
| 1452 | + - `--permission-mode plan`. Codey has no read-only planning mode, and says so | |
| 1453 | + rather than run a mode it does not have. Ask for a plan in the prompt, and | |
| 1454 | + `--disallowedTools Edit,Write,Bash` holds the run to it. | |
| 1455 | + - `--input-format stream-json`, and so a conversation fed in over stdin. The | |
| 1456 | + prompt is text. | |
| 1457 | + - `--include-partial-messages`: there are no `stream_event` lines, only whole | |
| 1458 | + messages. | |
| 1459 | + - `--mcp-config` and `--strict-mcp-config`. MCP servers come from | |
| 1460 | + [Codey's config](#mcp-servers). | |
| 1461 | + - `--settings`, `--setting-sources`, `--add-dir`, `--fallback-model`, | |
| 1462 | + `--session-id`, `--fork-session`, and `--resume` with no id, which in Claude | |
| 1463 | + Code opens a picker. | |
| 1464 | + - Piping a file in alongside a prompt. `cat log | claude -p "explain"` hands | |
| 1465 | + Claude Code both; Codey reads stdin only when there is no prompt otherwise, | |
| 1466 | + because a CI runner can leave stdin as a pipe nobody ever closes, and a run | |
| 1467 | + that waited on it would hang there for good. Put it in the prompt: | |
| 1468 | + `codey -p "explain: $(cat log)"`. | |
| 1469 | + - A prompt without `-p`, which in Claude Code starts an interactive session | |
| 1470 | + with that prompt. Codey ignores it and says so. | |
| 1471 | + - Tool names in the output are Codey's — `bash`, `read_file` — not Claude | |
| 1472 | + Code's. A script that looks for `"name":"Bash"` in the stream needs to look | |
| 1473 | + for `bash`. | |
| 1474 | + - The result object has no `permission_denials` or `modelUsage`, and lines | |
| 1475 | + carry no `parent_tool_use_id` other than `null`: subagents report through a | |
| 1476 | + tool result rather than in the parent's stream. | |
| 1477 | + | |
| 1343 | 1478 | ## Inside another editor |
| 1344 | 1479 | |
| 1345 | 1480 | Codey can be the agent behind somebody else's UI. It speaks the |
| @@ -1430,7 +1565,11 @@ a lot. | ||
| 1430 | 1565 | |
| 1431 | 1566 | **Approval prompts.** Read-only tools run unattended. `bash`, `edit_file`, |
| 1432 | 1567 | `write_file`, `web_search` and `web_fetch` ask, with "yes / no / always this exact one / always this tool" and |
| 1433 | - session memory. `/allowed` lists what you have agreed to. | |
| 1568 | + session memory. `/allowed` lists what you have agreed to. `--allowedTools` and | |
| 1569 | + `--disallowedTools` write the same decisions down ahead of time, in Claude | |
| 1570 | + Code's rule syntax — see [using it in place of | |
| 1571 | + `claude`](#using-it-in-place-of-claude) — and a deny rule there is checked | |
| 1572 | + before everything else, `-yolo` included. | |
| 1434 | 1573 | |
| 1435 | 1574 | Shell commands are parsed with `mvdan.cc/sh/syntax` so the prompt can tell you |
| 1436 | 1575 | what a command will actually run — `git status; rm -rf ~` is shown as running |
| @@ -1488,7 +1627,7 @@ internal/skills discovery and parsing of SKILL.md, Codey's own and Claude Code | ||
| 1488 | 1627 | internal/websearch the search command, the URL jail, HTML to text |
| 1489 | 1628 | internal/mcp MCP client: starts the configured servers, offers their tools |
| 1490 | 1629 | internal/config saved defaults: model, effort, approvals, web search, theme, diagnostics |
| 1491 | - internal/approval allow / deny / ask, with shell analysis | |
| 1630 | + internal/approval allow / deny / ask, with shell analysis and Claude Code's permission rules | |
| 1492 | 1631 | internal/ask questions the agent puts to you mid-task, and the tool for it |
| 1493 | 1632 | internal/hooks the lifecycle, published: fan-out, and the config's commands |
| 1494 | 1633 | internal/herdr reporting agent state to the herdr pane Codey is running in |