docs: document recent agent updates#411
Conversation
![poe-code-agent[bot]](https://avatars.githubusercontent.com/in/2645587?s=60&v=4){kind=small}
| | Argument | Required | Description | | ||
| |----------|----------|-------------| | ||
| | `agent` | Yes | Agent to spawn: `claude-code`, `codex`, `opencode`, `kimi`, `goose` | | ||
| | `agent` | Yes | Agent to spawn, such as `claude-code`, `codex`, `cursor`, `opencode`, `kimi`, `goose`, or `poe-agent`. | |
There was a problem hiding this comment.
This changed doc no longer passes npx prettier --check docs/README_FULL.md (the base version does), so the repository format check regresses. Please run npx prettier --write docs/README_FULL.md.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 83260f253b
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| ```bash | ||
| npx poe-code@latest wrap claude | ||
| # Also available: codex, opencode, kimi, goose | ||
| # Also available: codex, cursor, opencode, kimi, goose |
There was a problem hiding this comment.
wrap cursor is advertised in the quickstart, but the wrap command requires the provider to define isolatedEnv and throws Agent "cursor" does not support isolated configuration wrappers. otherwise; src/providers/cursor.ts defines spawn/install support but no isolated wrapper config. Users following this line will get an immediate failure instead of a Poe-routed Cursor session.
Useful? React with 👍 / 👎.
|
|
||
| # Setup a specific agent | ||
| npx poe-code@latest configure codex # (or claude, opencode, kimi, goose) | ||
| npx poe-code@latest configure codex # (or claude, cursor, opencode, kimi, goose) |
There was a problem hiding this comment.
cursor is documented here as a setup target, but the provider has requiresProvider: false and an empty manifest.configure, while the agent-spawn README says Cursor uses the authenticated cursor-agent account with no environment variables injected. Running poe-code configure cursor therefore only records a no-provider config and does not route Cursor API calls through Poe, so this quickstart points users at a setup path that cannot produce the advertised behavior.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1f3372480f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ## Resuming sessions | ||
|
|
||
| Pass `resumeThreadId` to continue a prior provider thread/session. Declarative agent configs decide where the resume arguments are inserted and how user-facing resume hints are rendered. Claude Code, Codex, Cursor, OpenCode, Kimi, Goose, and Poe Agent have resume mappings; Poe Agent persists its local message history under `~/.poe-code/sessions/`. |
There was a problem hiding this comment.
This package does not have a declarative spawn/resume mapping for poe-agent: allSpawnConfigs only registers Claude Code, Codex, Cursor, OpenCode, Kimi, and Goose, and resolveCliConfig throws when an agent has no spawn config. Users importing @poe-code/agent-spawn and following this line with spawn("poe-agent", { resumeThreadId: ... }) will fail before launch; if the intent is to describe the root CLI/SDK custom Poe Agent handler, it should be documented separately from agent-spawn's declarative mappings.
Useful? React with 👍 / 👎.
|
|
||
| #### Run a plan with follow-up checks | ||
|
|
||
| Gaslight runs a Markdown plan, then resumes the same agent thread with configured follow-up prompts such as testing, simplification, and commit checks. |
There was a problem hiding this comment.
When users follow this new quickstart after gaslight install, the scaffolded config has follow-ups, but the CLI wrapper passes @poe-code/agent-spawn.spawn into runGaslight; that low-level spawn returns only stdout/stderr/exitCode, while runGaslight throws before the first follow-up if result.threadId is missing. In that normal CLI-agent path the documented “resumes the same agent thread” flow stops after round 1 instead of running testing/commit checks.
Useful? React with 👍 / 👎.
poe-code-agent
Bot
force-pushed
the
agent/update-documentation
branch
from
1f33724 to
948412b
Compare
| | `openai/gpt-5.1-codex-mini` | | | ||
| | Model ID | Default | | ||
| | --------------------------- | ------- | | ||
| | `openai/gpt-5.2-codex` | Yes | |
There was a problem hiding this comment.
This default is out of sync with src/cli/constants.ts, where DEFAULT_CODEX_MODEL is openai/gpt-5.5. The table should also include the newer Codex model set shown later in this file.
| | `openai/gpt-5.2-codex` | Yes | | |
| | `openai/gpt-5.5` | Yes | |
| | `read` | Read-only, no modifications | `--permission-mode plan` | `-s read-only` | `--agent plan` | (none) | `GOOSE_MODE=chat` | | ||
| | Mode | Description | Claude Code Args | Codex Args | Cursor Args | OpenCode Args | Kimi Args | Goose | | ||
| | ------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------- | ---------------------------- | -------------- | ------------- | -------------------------- | | ||
| | `yolo` | Full access, no permission prompts | `--dangerously-skip-permissions` | `-s danger-full-access` | `--force --sandbox disabled` | (none) | `--yolo` | `GOOSE_MODE=auto` | |
There was a problem hiding this comment.
Codex yolo no longer maps to -s danger-full-access; packages/agent-spawn/src/configs/codex.ts uses --dangerously-bypass-approvals-and-sandbox.
| | `yolo` | Full access, no permission prompts | `--dangerously-skip-permissions` | `-s danger-full-access` | `--force --sandbox disabled` | (none) | `--yolo` | `GOOSE_MODE=auto` | | |
| | `yolo` | Full access, no permission prompts | `--dangerously-skip-permissions` | `--dangerously-bypass-approvals-and-sandbox` | `--force --sandbox disabled` | (none) | `--yolo` | `GOOSE_MODE=auto` | |
| | ----------- | ------------- | ---------- | ---------- | ------------- | ----- | --------- | ----------- | ------ | | ||
| | Claude Code | `claude-code` | `claude` | `claude` | JSON | Yes | Yes | Yes | Yes | | ||
| | Codex | `codex` | — | `codex` | TOML | Yes | Yes | Yes | Yes | | ||
| | OpenCode | `opencode` | — | `opencode` | JSON | No | No | Yes | Yes | |
There was a problem hiding this comment.
This summary should match the updated MCP serialization section and supportsMcpAtSpawn(): OpenCode has mcpEnv: serializeOpenCodeMcpEnv, so spawn-time MCP is supported.
| | OpenCode | `opencode` | — | `opencode` | JSON | No | No | Yes | Yes | | |
| | OpenCode | `opencode` | — | `opencode` | JSON | No | Yes | Yes | Yes | |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 948412b34e
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| | `agentArgs` | No | Additional arguments forwarded directly to the agent CLI. | | ||
| | Argument | Required | Description | | ||
| | ----------- | -------- | ------------------------------------------------------------------------------------------------------ | | ||
| | `agent` | Yes | Agent to spawn, such as `claude-code`, `codex`, `cursor`, `opencode`, `kimi`, `goose`, or `poe-agent`. | |
There was a problem hiding this comment.
Including poe-agent in the generic spawn list makes the adjacent --mode read|edit|auto|yolo documentation look applicable to it, but the custom createPoeAgentSpawnHandler drops options.mode when calling spawnPoeAgentWithAcp. In particular, poe-code spawn poe-agent --mode read ... still runs without Poe Agent's read policy, so users relying on this doc for a read-only run get a less constrained session than advertised.
Useful? React with 👍 / 👎.
Remove Cursor from wrap and configure quickstart targets because Cursor spawn support does not route calls through Poe provider configuration. Format docs/README_FULL.md with Prettier to restore the repository formatting check. Addresses review comments 3406958006, 3406961902, and 3406961905.
poe-code-agent
Bot
force-pushed
the
agent/update-documentation
branch
from
948412b to
48a7a2e
Compare
|
|
||
| ## Resuming sessions | ||
|
|
||
| Pass `resumeThreadId` to continue a prior provider thread/session. Declarative agent configs decide where the resume arguments are inserted and how user-facing resume hints are rendered. Claude Code, Codex, Cursor, OpenCode, Kimi, Goose, and Poe Agent have resume mappings; Poe Agent persists its local message history under `~/.poe-code/sessions/`. |
There was a problem hiding this comment.
@poe-code/agent-spawn still has no poe-agent spawn config, so package consumers following this sentence with spawn("poe-agent", { resumeThreadId }) hit Agent "poe-agent" has no spawn config. Poe Agent resume is handled by the top-level CLI/provider path instead.
| Pass `resumeThreadId` to continue a prior provider thread/session. Declarative agent configs decide where the resume arguments are inserted and how user-facing resume hints are rendered. Claude Code, Codex, Cursor, OpenCode, Kimi, Goose, and Poe Agent have resume mappings; Poe Agent persists its local message history under `~/.poe-code/sessions/`. | |
| Pass `resumeThreadId` to continue a prior provider thread/session. Declarative agent configs decide where the resume arguments are inserted and how user-facing resume hints are rendered. Claude Code, Codex, Cursor, OpenCode, Kimi, and Goose have resume mappings. |
| | `-C, --cwd <path>` | Current dir | Working directory for the agent. | | ||
| | `--stdin` | `false` | Read the prompt from stdin. | | ||
| | `-i, --interactive` | `false` | Launch in interactive TUI mode (inherits stdio). | | ||
| | `--mode <mode>` | Prompted; `--yes` uses `yolo` | Permission mode: `yolo`, `auto`, `edit`, or `read`. Unsupported modes fail before launch with the supported-mode list. | |
There was a problem hiding this comment.
Since this section now includes poe-agent as a spawn target, this overstates --mode: createPoeAgentSpawnHandler() does not pass options.mode into spawnPoeAgentWithAcp, so poe-code spawn poe-agent --mode read is not constrained by the documented read mode.
| | `openai/gpt-5.1-codex-mini` | | | ||
| | Model ID | Default | | ||
| | --------------------------- | ------- | | ||
| | `openai/gpt-5.2-codex` | Yes | |
There was a problem hiding this comment.
This default is still out of sync with src/cli/constants.ts, where DEFAULT_CODEX_MODEL is openai/gpt-5.5.
| | `openai/gpt-5.2-codex` | Yes | | |
| | `openai/gpt-5.5` | Yes | |
| | `read` | Read-only, no modifications | `--permission-mode plan` | `-s read-only` | `--agent plan` | (none) | `GOOSE_MODE=chat` | | ||
| | Mode | Description | Claude Code Args | Codex Args | Cursor Args | OpenCode Args | Kimi Args | Goose | | ||
| | ------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------- | ---------------------------- | -------------- | ------------- | -------------------------- | | ||
| | `yolo` | Full access, no permission prompts | `--dangerously-skip-permissions` | `-s danger-full-access` | `--force --sandbox disabled` | (none) | `--yolo` | `GOOSE_MODE=auto` | |
There was a problem hiding this comment.
Codex yolo no longer maps to -s danger-full-access; packages/agent-spawn/src/configs/codex.ts uses --dangerously-bypass-approvals-and-sandbox.
| | `yolo` | Full access, no permission prompts | `--dangerously-skip-permissions` | `-s danger-full-access` | `--force --sandbox disabled` | (none) | `--yolo` | `GOOSE_MODE=auto` | | |
| | `yolo` | Full access, no permission prompts | `--dangerously-skip-permissions` | `--dangerously-bypass-approvals-and-sandbox` | `--force --sandbox disabled` | (none) | `--yolo` | `GOOSE_MODE=auto` | |
| | ----------- | ------------- | ---------- | ---------- | ------------- | ----- | --------- | ----------- | ------ | | ||
| | Claude Code | `claude-code` | `claude` | `claude` | JSON | Yes | Yes | Yes | Yes | | ||
| | Codex | `codex` | — | `codex` | TOML | Yes | Yes | Yes | Yes | | ||
| | OpenCode | `opencode` | — | `opencode` | JSON | No | No | Yes | Yes | |
There was a problem hiding this comment.
OpenCode has mcpEnv: serializeOpenCodeMcpEnv, so supportsMcpAtSpawn("opencode") returns true and this summary should say MCP spawn is supported.
| | OpenCode | `opencode` | — | `opencode` | JSON | No | No | Yes | Yes | | |
| | OpenCode | `opencode` | — | `opencode` | JSON | No | Yes | Yes | Yes | |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 48a7a2e08a
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| ```ts | ||
| import { startManagedProcess, stopManagedProcess } from "@poe-code/process-launcher"; | ||
|
|
||
| const record = await startManagedProcess({ |
There was a problem hiding this comment.
This example calls startManagedProcess() without a spawnDaemon implementation, but StartManagedProcessOptions requires that callback and startManagedProcess calls options.spawnDaemon(spec.id) unconditionally. Users copying the README sample will either get a TypeScript error or a runtime options.spawnDaemon is not a function before the managed process can start, so the usage example needs to show how to provide the daemon launcher (or use an API that does not require one).
Useful? React with 👍 / 👎.
1 participant
Summary
automode, resume thread IDs, Cursor spawn coverage, OpenCode MCP injection, and activity timeouts.ingestconfig generation.agent-spawn,agent-gaslight, andagent-evaloutput formats.agent-eval,process-launcher,terminal-png,tiny-stdio-mcp-server,toolcraft,toolcraft-schema, andtoolcraft-openapi.Validation
git log --since='24 hours ago' --onelinegit diff --checknpx prettier --check README.md docs/README_FULL.md packages/agent-spawn/README.md packages/agent-gaslight/README.md packages/agent-eval/README.md packages/toolcraft/README.md packages/toolcraft-schema/README.md packages/toolcraft-openapi/README.md packages/tiny-stdio-mcp-server/README.md packages/terminal-png/README.md packages/process-launcher/README.md