coppice
AGENTS.md27 starsChanged 7 days agoApache-2.0View on GitHub
Coppice is a local desktop agent workspace: Trello-like board, tickets, comments, and (from M03) agent execution. It ships as an Electron app that bundles PostgreSQL, the Rust server and the SPA, so end users install nothing else (.dmg / .deb built from a git tag; Docker Compose remains the dev/CI stack). Philosophy and full product design live in docs/philosophy/. Status: M01–M09 are complete (M07 was narrowed to git/PR + forge secrets). M10 — Plugins Parts 1, 2a, and 2b are…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository8 other files it gives its agents.
The file
We split this AGENTS.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Milestones are sequential: Read the current milestone spec in docs/milestones/ before implementing.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Coppice — Agent Guide
Coppice is a local desktop agent workspace: Trello-like board, tickets, comments, and (from M03) agent execution. It ships as an Electron app that bundles PostgreSQL, the Rust server and the SPA, so end users install nothing else (.dmg / .deb built from a git tag; Docker Compose remains the dev/CI stack). Philosophy and full product design live in docs/philosophy/.
Status: M01–M09 are complete (M07 was narrowed to git/PR + forge secrets). M10 — Plugins Parts 1, 2a, and 2b are implemented: tool-first harness (MCP gateway /mcp, core tools, built-in skills), plugin dirs / git install / enablement / plugin skills, and the plugin MCP proxy (stdio + HTTP, encrypted settings, Test button, Tools & Skills tab, console tool titles). M10 still open: live verification of the claude-code, codex, and kilo-code gateway wiring (manual acceptance, needs their CLIs). M11 — Desktop release is implemented (coppice-server desktop with bundled Postgres 16, Electron shell, electron-builder packaging, tag-triggered release workflow); still open: the live tag check and manual install acceptance with a real connector (MockProvider is not in desktop or release builds). Next implement: M12 — Beta Release (public site, Electron-first docs, macOS arm64 .dmg and Linux x64 .deb), still blocked by those M11 leftovers and by M10's manual connector verification. Then M13 — Security & sandbox, then M14 — Role-owner agents.
Must read before coding
- Milestones are sequential. Read the current milestone spec in
docs/milestones/before implementing. Do not skip acceptance criteria or pull scope from later milestones. - Docker Compose is the dev path — use the default stack only. Agents and CI must use
deploy/docker-compose.ymlviamake compose-up,make bootstrap,make e2e-smoke, andmake e2e-smoke-m03. That stack runs Postgres, server, and web together (ports 5432, 5000, 5001). The web image is production (vite build+ nginx, proxies/api//wsto the API). The server container auto-migrates on start and does not read the repoconfig.toml. Do not use the human local stack (deploy/docker-compose.local.yml,make compose-local-up,make server-dev,make web-dev) — that alternate path exists for human hot-reload dev (Postgres on 5433, API/web on host). If smoke or integration tests fail, fix the default stack or free ports 5432/5000/5001; do not fall back to the local compose file. Do not start Postgres or services with ad-hocdocker run. See docs/development.md. The desktop app is an additional path, not a replacement: verify packaging withmake desktop-testandmake desktop-dist-dir desktop-smoke(desktop/README.md). - Server owns state. API handlers are thin; business rules live in
server/src/services/andserver/src/domain/. The SPA does not invent status transitions or workflow rules. - Auth is session + CSRF. httpOnly cookie sessions; mutations require
X-CSRF-Token. Integration tests authenticate via session cookie (seeserver/tests/common/mod.rs). - Agent tests use
MockProvider. Mock is for CI and automated tests only, not an end-user connector. Fixtures:fixtures/agent-responses/. Desktop and release builds omit themock-providerfeature (docs/providers/mock.md). The five real connectors (Claude Code, Codex, Cursor, OpenCode, Kilo Code) run as host CLIs. Docker is only needed for the Compose dev stack. - CI must pass.
make test(embedded Postgres, no Docker),cargo clippy --workspace -- -D warnings, andmake web-test(plusmake desktop-testwhen touchingdesktop/). Clippy warnings are errors. After a successful full Rust test pass for your task, runmake cleanto reclaim disk (target/can grow to 10+ GB). Do not run it before every incrementalcargo testduring development — only when you are done with the task. - Fast verification during work. Do not run
make testwhile iterating — even in parallel (cargo-nextest; serial fallback without it) the full suite builds every integration binary. Usemake test-unit(lib only),make test-smoke(lib + a few integration files), targetedcargo test -p coppice-server --features embedded-test-db <filter>, ormake web-test. Reservemake testfor final acceptance. Rust tests do not requiremake compose-uporDATABASE_URL. - Repositories. Admin registers git checkouts by
local_path(Settings → Repositories). Coppice creates worktrees only — no server-sidegit clone. Optionalremote_urlfor metadata/PR (M07, done). Bind-mount host repos into the server container in Docker. - Agent execution env.
WORKTREES_PATH,AGENT_WORKER_COUNT. (AGENT_DEFAULT_PROVIDERis obsolete and ignored.) Smoke:make e2e-smoke-m03. Context long-running (continued,splitTickets); smoke:make e2e-smoke-m06. Governed knowledge (M06): Postgres full-text search, no embeddings; an admin-selected agent compacts Done tickets in batches; smoke:make e2e-smoke-m06-knowledge. The five real connectors run as host CLIs. In Compose, sign in withcoppice connector …on the server container (M08) instead of bind-mounting host CLIs. Runs are tool-first:.agent/context.mdis slim and agents read tickets, knowledge and skills through the Coppice MCP gateway atPOST /mcp, authenticated by a per-run token (COPPICE_MCP_URL/COPPICE_MCP_TOKEN) and finished withresult_submit. Connectors configure it per run only — never the worktree or a global CLI config — and fail withmcp_unavailablewhen they cannot (per-connector status). Plugins: Claude Code / Cursor format folders; their skills load as<plugin>:<skill>and their MCP servers are proxied through the gateway as<plugin>__<tool>(architecture); smoke:make e2e-smoke-m10.
Monorepo (quick map)
| Path | Role |
server/ | Rust API (Axum, SQLx) |
web/ | React SPA (Vite, TanStack Query) |
cli/ | Operator CLI (coppice migrate, bootstrap, health, connector) |
connectors/ | Static connector descriptors (ids, capabilities, run contract, MCP wiring, console kind) shared by server and CLI |
desktop/ | Electron shell, electron-builder packaging, release scripts (spawns coppice-server desktop) |
deploy/ | Docker Compose + Dockerfiles |
e2e/ | Browser smoke tests |
docs/ | Contributor docs: philosophy, milestones, development |
website/ | Astro marketing site and user docs (M12). Primary product docs; docs/ stays for contributors |
Read on demand
| Topic | Doc |
| Local setup & commands | docs/development.md, docs/operations.md |
| Code layout & conventions | docs/architecture.md |
| Testing strategy | docs/testing.md |
| Using & writing plugins | docs/plugins.md, example: examples/plugins/hello-coppice |
| Roadmap & acceptance criteria | docs/milestones/README.md |
| Product principles & UX | docs/philosophy/final_agent_workspace_product_design.md |
| Stack choices | docs/philosophy/final_agent_workspace_framework_selection.md |
| Web visual design | docs/web/DESIGN.md |
| English prose in READMEs, the site, contributor docs, and UI copy | .agents/skills/english-technical-writing/SKILL.md |
Vietnamese prose in README.vi.md, Vietnamese site docs, and Vietnamese UI strings | .agents/skills/vietnamese-technical-writing/SKILL.md |
Simplified Chinese prose in README.zh-CN.md, website/src/content/docs/zh-cn/, and website/src/i18n/**/zh-cn.ts | .agents/skills/zh-cn-technical-writing/SKILL.md |
Taiwan Traditional Chinese prose in README.zh-TW.md, website/src/content/docs/zh-tw/, and website/src/i18n/**/zh-tw.ts | .agents/skills/zh-tw-technical-writing/SKILL.md |
Hong Kong Traditional Chinese prose in README.zh-HK.md, website/src/content/docs/zh-hk/, and website/src/i18n/**/zh-hk.ts | .agents/skills/zh-hk-technical-writing/SKILL.md |
Japanese prose in README.ja.md, website/src/content/docs/ja/, and website/src/i18n/**/ja.ts | .agents/skills/ja-technical-writing/SKILL.md |
French prose in README.fr.md, website/src/content/docs/fr/, and website/src/i18n/**/fr.ts | .agents/skills/fr-technical-writing/SKILL.md |
Blog posts in website/src/content/blog/ (topic, structure, how much Coppice detail) | .agents/skills/blog-writing/SKILL.md |
Language authoring
When drafting, reviewing, or rewriting English in the root README.md, website/, contributor docs/, or UI strings, read .agents/skills/english-technical-writing/SKILL.md before editing. When doing the same for Vietnamese in README.vi.md, website/src/content/docs/vi/, or website/src/i18n/**/vi.ts, read .agents/skills/vietnamese-technical-writing/SKILL.md. When doing the same for Simplified Chinese in README.zh-CN.md, website/src/content/docs/zh-cn/, or website/src/i18n/**/zh-cn.ts, read .agents/skills/zh-cn-technical-writing/SKILL.md. When doing the same for Taiwan Traditional Chinese in README.zh-TW.md, website/src/content/docs/zh-tw/, or website/src/i18n/**/zh-tw.ts, read .agents/skills/zh-tw-technical-writing/SKILL.md. When doing the same for Hong Kong Traditional Chinese in README.zh-HK.md, website/src/content/docs/zh-hk/, or website/src/i18n/**/zh-hk.ts, read .agents/skills/zh-hk-technical-writing/SKILL.md. When doing the same for Japanese in README.ja.md, website/src/content/docs/ja/, or website/src/i18n/**/ja.ts, read .agents/skills/ja-technical-writing/SKILL.md. When doing the same for French in README.fr.md, website/src/content/docs/fr/, or website/src/i18n/**/fr.ts, read .agents/skills/fr-technical-writing/SKILL.md. Use the skill that matches the language being edited. These skills are repository guidance for this checkout. They are not Coppice built-in, marketplace, or end-user plugin skills, and they do not change running agents.
Repository skills live in .agents/skills/. .claude/skills is a symlink to that folder, so Claude Code, Codex, Cursor, and other agents working in this checkout read the same files. Edit them in .agents/skills/ only. They are for contributors to this repository, not Coppice plugins: do not copy them into a root skills/ directory, server/builtin-plugins/, or server/marketplace/, which the server loads into end-user agents. Further languages are separate research loops. Do not invent them from the English, Vietnamese, Simplified Chinese, Taiwan Traditional Chinese, Hong Kong Traditional Chinese, Japanese, or French skill. A style pass leaves commands, configuration keys, URLs, permissions, and locked positioning as they are.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

