Agent Cockpit

Agent Cockpit is a model-agnostic, Markdown-first control plane for working with coding and research agents. It is not an agent runtime and does not replace tools like Codex, Claude Code, or Gemini CLI. It is a lightweight methodology layer for turning repeated AI work into scoped tasks, explicit facts, completion gates, handoff documents, and reusable skills.

In short: your runtime makes the model use tools; Agent Cockpit makes the work bounded, evidence-backed, reviewable, and recoverable.

Good Fit

• You often ask coding agents or research agents to do research, planning, demos, scripts, or handoff documents.
• You want each task to have facts, a brief, a ledger, and a deliverable.
• You want explicit gates for risky actions such as publishing, deleting data, external messages, and batch commits.
• You want each task to use the latest profile and Markdown memory to decide whether to execute, state an assumption, clarify, or wait for authorization.
• You want repeated work to become profiles, skills, and reusable methods.

Not A Good Fit

• You want a complete agent runtime out of the box.
• You want built-in model calls, sandboxing, browser control, or cloud execution.
• You want to reuse someone else's private tasks, knowledge base, or working memory.

What Is Included

• method/: dynamic task profiles, four-level clarification policy, working rules, readiness checks, completion gates, task ledgers, recovery, and workspace isolation.
• profiles/: task templates for research, proposals, demos, toolmaking, and handoff.
• skills/: reusable local skills that are generic enough to publish.
• adapters/: runtime routing notes for using the same method across agent clients.
• scripts/: setup scripts for copying the public template into a private workspace.
• examples/: safe templates for building your own private profile, state file, task folders, registries, journal, decisions, and knowledge base.

Languages

• README.md is English by default for GitHub.
• Chinese readers can start from README.zh.md.
• Documents that have been genuinely translated use .en.md / .zh.md suffixes. Do not duplicate the same text as a fake translation; historical documents that still need translation keep their original filenames.

v0.3 CLI

v0.3.0 is the first installable Agent Cockpit CLI release. The latest patch is v0.3.1. It is available from the GitHub tag, requires Python 3.10+ and Git, and supports macOS, Linux, and WSL. It is not published to PyPI:

pipx install git+https://github.com/cyuanxv/agent-cockpit.git@v0.3.1
# or
uv tool install git+https://github.com/cyuanxv/agent-cockpit.git@v0.3.1

Install from a local clone:

python3 -m pip install .

Create a minimal private workspace and check it:

cockpit init --runtime codex ~/my-agent-cockpit
cockpit --root ~/my-agent-cockpit doctor

init never overwrites existing files and performs no partial write when it finds a conflict. Edit user-profile.md and .cockpit/config.json before the first task.

Private Directories

This public repository does not include real private user-profile, project-state, tasks/, repo-config/, journal/, decision-records/, or kbs/ data. Build your private workspace from the templates in examples/.

See docs/private-workspace-migration.en.md for the full migration path. Chinese version: docs/private-workspace-migration.zh.md.

User Profile

If you do not know how to write a user profile, start with method/user-profile-quickstart.md. The recommended workflow is to ask several agents you already use to summarize your collaboration style, then manually remove private details, merge duplicates, and keep only stable preferences and safety boundaries.

Profile-Aware Clarification

method/profile-context.md tells an agent how to build a temporary task profile from the current base profile, user-selected Markdown files or directories, and the current conversation. method/clarification-policy.md then makes one of four decisions:

1. Execute directly when the request is clear and low risk.
2. State a reversible assumption and continue.
3. Ask 1-3 questions when a hidden choice would materially change the result.
4. Stop for explicit authorization before external writes, publication, deletion, payment, permission changes, private-data handling, or irreversible actions.

After initialization, customize the generated repo-config/profile-sources.md and repo-config/clarification-policy.md. Every Cockpit policy is configurable, but lowering a safety level requires a specific acknowledgement and visible warning, and can never override runtime or repository hard gates.

Task Worktree Lifecycle

cockpit --root ~/my-agent-cockpit repos
cockpit --root ~/my-agent-cockpit start my-task --no-fetch
cockpit --root ~/my-agent-cockpit status my-task
cockpit --root ~/my-agent-cockpit prepare my-task \
  --repo workspace --path path/to/file --message "Describe the change"
cockpit --root ~/my-agent-cockpit finish my-task --dry-run

finish integrates only after explicit authorization and the configured confirmation phrase. Cleanup is a separate gate: first run cleanup <task-id> --dry-run, then explicitly pass --confirm cleanup. It refuses dirty, review-pending, repair-pending, or unintegrated tasks.

Preview migration from repo-config/git-repo-policies.json without writing:

cockpit --root ~/my-agent-cockpit migrate --dry-run
cockpit --root ~/my-agent-cockpit migrate --confirm migrate

The repository-local scripts/init-cockpit.sh remains available for copying the full methodology template and public Skills. The new cockpit init creates a minimal runnable workspace.

Why Agent Cockpit

Read docs/why-agent-cockpit.en.md for the project rationale. Chinese version: docs/why-agent-cockpit.zh.md.

For a publication-ready overview, read docs/launch-article.en.md. Chinese version: docs/launch-article.zh.md.

Release Notes

The v0.3.0 release notes are in docs/release-v0.3.0-installable-worktree-cli.en.md. Chinese version: docs/release-v0.3.0-installable-worktree-cli.zh.md.

The v0.3.1 patch is documented in CHANGELOG.md.

The v0.2.0 release notes remain in docs/release-v0.2.0-profile-aware-foundation.en.md.

Historical public-preview notes remain in docs/release-v0.1.0-public-preview.en.md.

Maintenance And Contributions

• Changes: CHANGELOG.md
• Security reports: SECURITY.md
• Contributions: CONTRIBUTING.md

Privacy Boundary

This repository is a sanitized methodology skeleton. Replace example paths, registries, project names, and workspace conventions with your own private versions before use. Real user data, business data, account credentials, and internal company information should stay in your private workspace and should not enter a public repository.

License

Agent Cockpit is released under the MIT License.