External Subagents
https://github.com/obra/external-subagents- Category
- AI Agents
- Rank
- No. 2048Tools index
- Pricing
- Open Source
- Type
- TOOL
- Builder
- obra
- GitHub
- 24 stars
- Date
About
Codex subagent CLI and tooling.
What it does
External Subagents runs separate Codex threads so long tasks do not fill the controlling agent’s context. It launches work in the background by default, stores thread metadata and message history locally, and provides commands to resume, inspect, watch, wait for, label, list, or archive that work.
Why it's ranked here
This is a focused orchestration layer with unusually practical lifecycle controls. Batch manifests, detached execution, ownership checks, safe permission mappings, local diagnostics, and resumable threads address real operational friction. The setup remains developer-oriented, and its value depends on already using compatible command-line agents.
What's good
The strongest feature is observability without waking the agent process. Inspection commands read local registries and NDJSON logs, while launch records preserve immediate failures and stderr details. Controller ownership prevents one session from operating another session’s threads. Dry runs and composed-prompt printing also make delegation easier to check before execution.
Tradeoffs
Installation requires Node 20 or newer, npm, a source checkout, dependency installation, and a build step. Codex must already be installed and available on the command path. State is local rather than a shared service. The optional Claude backend needs an environment flag, and workspace-only sandbox fallback may copy credentials into a local ignored directory that must remain secret.
How to use it well
Use it when a Codex workflow needs several long-running research, coding, or inspection tasks with explicit permissions and later follow-ups. Launch batches from structured JSON, label threads, check diagnostics after detached starts, then wait on selected results. It does not provide a hosted queue, remote team dashboard, or standalone agent runtime.
Technical notes+
README.md defines the command surface, Node and npm requirements, local state layout, controller isolation, safe policy mapping, and optional Claude feature flag. dev/build.mjs uses esbuild to create a bundled Node 20 CommonJS executable with a shebang and source map, while dev/tsup.config.ts describes an alternate ESM bundle. dev/src/lib/backends.ts normalizes Codex and Claude event streams and maps read-only or workspace-write permissions. dev/src/lib/registry.ts uses file locking plus temporary-file rename for registry updates. dev/src/lib/paths.ts centralizes state, logs, archives, and launch-error locations. dev/src/commands/list.ts filters owned threads, sorts running work first, cleans stale launch records, and reports pending or failed launches.
Observed
- Primary language
- TypeScript
- Interface
- Command-line interface for starting, resuming, inspecting, waiting on, labeling, listing, and archiving agent threads
- Runtime
- Node.js 20 or newer with npm 10 or newer
- Packaging
- Source checkout followed by npm install and a local build that emits an executable bundle
- Backends
- Codex CLI by default, with an optional feature-flagged Claude CLI backend
- State model
- Local JSON registry metadata and per-thread NDJSON message logs
- Safety model
- Read-only and workspace-write permission levels, dangerous policies refused, and controller ownership enforced
Read from README.md, dev/build.mjs, dev/demo-watch.ts, dev/tsup.config.ts, dev/eslint.config.js, dev/run-prek-install.mjs, dev/src/lib/logs.ts, dev/src/lib/time.ts, dev/src/lib/paths.ts, dev/src/lib/prompt.ts, dev/src/commands/log.ts, dev/src/lib/backends.ts, dev/src/lib/personas.ts, dev/src/lib/registry.ts, dev/src/commands/list.ts.
What it can do
Execute subagent commands via CLI
Command line arguments and parameters → Command execution results
Generate code from natural language prompts
Natural language description of desired code → Generated code in specified programming language
Deploy and manage external subagents
Subagent configuration and deployment parameters → Running subagent instances
Monitor subagent performance and status
Subagent identifiers or process names → Performance metrics and status reports
Configure subagent workflows and pipelines
Workflow definitions and configuration files → Configured automation pipelines
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.