{"_id":"@aaronlps/copse","_rev":"2-058c41027e69c42ed90bfc5a2e3a3760","name":"@aaronlps/copse","dist-tags":{"latest":"0.4.1"},"versions":{"0.4.0":{"name":"@aaronlps/copse","version":"0.4.0","keywords":["git","worktree","cli","agent","multi-agent"],"license":"MIT","_id":"@aaronlps/copse@0.4.0","maintainers":[{"name":"aaronlps","email":"shi.liping@hotmail.com"}],"homepage":"https://github.com/AaronLPS/copse#readme","bugs":{"url":"https://github.com/AaronLPS/copse/issues"},"bin":{"copse":"src/cli.mjs"},"dist":{"shasum":"6e490dba7a157f7c2d48d1e6f33537bc5ebe8619","tarball":"https://registry.npmjs.org/@aaronlps/copse/-/copse-0.4.0.tgz","fileCount":29,"integrity":"sha512-W0zKDc1v6BHlQgtP4PAND5pX9D2tEY2xpjaKe0yUMyVetc0WsceMTqE0R5fcfJxZ7gT/KIMHUUbQnistOhFdMA==","signatures":[{"sig":"MEYCIQCboThgGoC0EDTi0xofNRbUvyrXfBZ8GsA/Z5+HwxB72wIhALj0Zd2vZRXIon0yTm/8772BSDxnBBEPO/JqQQAi1UiG","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":136503},"type":"module","engines":{"node":">=20"},"gitHead":"dbb058082abc7a60f4fab25355bb45e61df25979","scripts":{"test":"node --test test/*.mjs","check":"node scripts/check-syntax.mjs","test:package":"node scripts/package-smoke.mjs","test:coverage":"node --test --experimental-test-coverage --test-coverage-include=src/** test/*.mjs","test:agents:live":"node scripts/live-agent-smoke.mjs"},"_npmUser":{"name":"aaronlps","email":"shi.liping@hotmail.com"},"repository":{"url":"git+https://github.com/AaronLPS/copse.git","type":"git"},"_npmVersion":"11.8.0","description":"Many agent sessions, one repository, no collisions.","directories":{},"_nodeVersion":"24.13.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/copse_0.4.0_1786728177045_0.4084120824610229","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"_id":"@aaronlps/copse@0.4.1","bin":{"copse":"src/cli.mjs"},"bugs":{"url":"https://github.com/AaronLPS/copse/issues"},"dist":{"shasum":"d0169b4a6db9971e1305988193c9c9327d283bfe","tarball":"https://registry.npmjs.org/@aaronlps/copse/-/copse-0.4.1.tgz","integrity":"sha512-ASf1OssFd6TlaMS8O64gqlvg5RUb7I2JdeL4/eIyyDx/q/nh9j77qWM66Jnct5rZXjz+TIw/nKrY6Y2YrofBxQ==","fileCount":30,"unpackedSize":138706,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHSpfm2I39zKyKRMmWmHHtAZ4GRBOp01xhoKnQkdNHu5AiB1NtXQYIwAkZNTHvYpvltcKdgNHCQGweeceQRhW8EGTA=="}]},"name":"@aaronlps/copse","type":"module","_from":"file:/tmp/copse-release-0.4.1/aaronlps-copse-0.4.1.tgz","engines":{"node":">=20"},"license":"MIT","scripts":{"test":"node --test test/*.mjs","check":"node scripts/check-syntax.mjs","test:package":"node scripts/package-smoke.mjs","test:coverage":"node --test --experimental-test-coverage --test-coverage-include=src/** test/*.mjs","test:agents:live":"node scripts/live-agent-smoke.mjs"},"version":"0.4.1","_npmUser":{"name":"aaronlps","email":"shi.liping@hotmail.com","approver":{"name":"aaronlps","email":"shi.liping@hotmail.com"}},"homepage":"https://github.com/AaronLPS/copse#readme","keywords":["git","worktree","cli","agent","multi-agent"],"_resolved":"/tmp/copse-release-0.4.1/aaronlps-copse-0.4.1.tgz","_integrity":"sha512-ASf1OssFd6TlaMS8O64gqlvg5RUb7I2JdeL4/eIyyDx/q/nh9j77qWM66Jnct5rZXjz+TIw/nKrY6Y2YrofBxQ==","repository":{"url":"git+https://github.com/AaronLPS/copse.git","type":"git"},"_npmVersion":"11.19.0","description":"Many agent sessions, one repository, no collisions.","directories":{},"maintainers":[{"name":"aaronlps","email":"shi.liping@hotmail.com"}],"_nodeVersion":"24.13.1","publishConfig":{"access":"public"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/copse_0.4.1_1786732080026_0.2584886472324295"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-14T17:22:56.874Z","modified":"2026-08-14T18:28:00.316Z","0.4.0":"2026-08-14T17:22:57.212Z","0.4.1":"2026-08-14T18:28:00.132Z"},"bugs":{"url":"https://github.com/AaronLPS/copse/issues"},"license":"MIT","homepage":"https://github.com/AaronLPS/copse#readme","keywords":["git","worktree","cli","agent","multi-agent"],"repository":{"url":"git+https://github.com/AaronLPS/copse.git","type":"git"},"description":"Many agent sessions, one repository, no collisions.","maintainers":[{"name":"aaronlps","email":"shi.liping@hotmail.com"}],"readme":"

\"copse\"

\n\nMany agent sessions, one repository, no collisions.\n\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)\n[![test](https://github.com/AaronLPS/copse/actions/workflows/copse.yml/badge.svg)](https://github.com/AaronLPS/copse/actions/workflows/copse.yml)\n[![node: >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)\n[![dependencies: 0](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)\n\ncopse is the repository framework for running Claude Code, Codex, or ordinary\nshell-driven feature work in parallel. It gives every feature a deterministic\nGit worktree, carries ignored local files such as `.env`, installs shared Git\nand agent hooks, records ownership, dependencies, live sessions, and shared\nresources, runs one verification path locally and in CI, and closes PR\ncreation, merge, refresh, and cleanup.\n\nIt coordinates mechanics, not product judgment: copse does not choose tasks,\nschedule models, or automatically resolve semantic merge conflicts.\n\n## Quickstart\n\ncopse requires Node 20 or newer and has no runtime dependencies. Bootstrap the\ncurrent GitHub distribution and persist that exact source in every generated\nforward with one command:\n\n```sh\nnpx github:AaronLPS/copse init --apply \\\n --runner-package github:AaronLPS/copse\n```\n\nFor a read-only preview, omit `--apply`. The apply form creates only absent\nwiring, merges copse hooks into existing Codex/Claude settings, and never\noverwrites a consumer-owned instruction or workflow file. For production use\nfrom GitHub, pin the package spec to a reviewed commit or tag.\n\nAfter the package is released, use the pinned release form separately:\n\n```sh\nnpx @aaronlps/copse@0.4.1 init --apply \\\n --runner-package @aaronlps/copse@0.4.1\n```\n\n`--runner-package` stores `npx --yes ` in `copse.config.json`, so\nGit, Codex, Claude, and CI keep invoking the selected distribution rather than\ndepending on the temporary path used by `npx` during bootstrap.\n\nThen start isolated work:\n\n```sh\ncopse claim feat/inbox-filter --owner alice --depends-on feat/search-api --resource port:3000\ncopse start feat/inbox-filter --agent codex --owner alice\n# or: copse start feat/inbox-filter --agent claude\n# or: copse start feat/inbox-filter -- npm run dev\n```\n\n`start` finds or creates the worktree, claims the feature when necessary, and\nholds an exclusive process-aware session lease while the command runs. A\nsecond agent cannot enter the same feature worktree; dead processes and expired\nheartbeats are reclaimed. A child process cannot change its parent shell's\ndirectory, so this launcher—not a fragile `cd` hook—is the reliable entry point.\n\n## Lifecycle\n\n```mermaid\nflowchart LR\n I[\"copse init --apply\"] --> C[\"claim feature\"]\n C --> S[\"copse start\"]\n S --> W[\"agent works in isolated worktree\"]\n W --> V[\"copse verify\"]\n V --> P[\"copse pr\"]\n P --> L[\"copse land --yes\"]\n L --> D[\"release coordination state
and safely remove worktree\"]\n```\n\nThe main worktree stays on `baseBranch`. Git hooks reject commits and pushes to\nprotected branches and reject illegal feature branch names. Repository-local\nCodex and Claude Code hooks add worktree context at session start and reject\nfeature edits attempted in the main worktree. CI and a GitHub ruleset remain\nthe backstop when agent hooks are disabled or untrusted.\n\n## Commands\n\n```text\ncopse init [--apply] [--ci mode] [--runner-package spec]\n inspect/apply repository wiring\ncopse new create a worktree and carry local files\ncopse start [--agent name] create/find it and launch an agent\ncopse claim [options] record owner and dependencies\ncopse release mark a dependency released\ncopse list [--json] worktrees, PRs, ownership and blockers\ncopse verify doctor, then configured argv checks\ncopse pr [branch] [--draft] verify and create a pull request\ncopse land [branch] [--yes] gate, merge and safely clean up\ncopse drop remove only when nothing can be lost\ncopse doctor validate wiring and worktree state\ncopse protect [--apply] preview/apply the GitHub ruleset\ncopse hook internal forward target\n```\n\nSee [the command reference](docs/commands.md) for preconditions, dry-run\nbehavior, and recovery paths.\n\n## Configuration\n\n`copse.config.json` declares facts and argv arrays; configured commands never\ngo through a shell.\n\n```json\n{\n \"baseBranch\": \"main\",\n \"releaseBranch\": null,\n \"branchPrefixes\": [\"feat\", \"fix\", \"docs\", \"chore\"],\n \"carryFiles\": [\".env.test\"],\n \"carryDirs\": [\"supabase/.temp\"],\n \"install\": [\"pnpm\", \"install\"],\n \"verify\": [[\"pnpm\", \"test\"], [\"pnpm\", \"lint\"]],\n \"agents\": {\n \"codex\": [\"codex\"],\n \"claude\": [\"claude\"]\n },\n \"coordinationFile\": \".copse/features.json\",\n \"coordinationBackend\": \"local\",\n \"leaseTimeoutSeconds\": 300,\n \"leaseHeartbeatSeconds\": 30,\n \"resources\": { \"feat/inbox-filter\": [\"port:3000\"] },\n \"ciMode\": \"auto\",\n \"ciSetup\": [],\n \"runner\": [\"npx\", \"--yes\", \"@aaronlps/copse\"]\n}\n```\n\nAll defaults and validation rules are in\n[the configuration reference](docs/configuration.md).\n\n## Agent integration and trust\n\n`init --apply` writes forwards in `.codex/hooks.json`,\n`.claude/settings.json`, `AGENTS.md`, and `CLAUDE.md`. Codex requires review of\nnew or changed non-managed project hooks; use `/hooks` to inspect and trust\nthem. Claude Code exposes its project hooks through its own `/hooks` browser.\nThe generated commands delegate to the configured `runner`, so upgrades live\nin the package rather than copied hook implementations.\n\nGit hook wrappers live in `.copse/hooks`. During onboarding, copse records the\nprevious active hook path in clone-local `copse.previousHooksPath`, then runs\nthat hook after copse policy succeeds. Existing Husky or custom hook files are\nnot edited; the `` value represents the clone's standard `.git/hooks`\ndirectory.\n\nBy default live ownership, leases, and resources are stored in Git's common directory at\n`.git/copse/features.json`, immediately visible from all worktrees without\ndirtying a branch. `coordinationBackend: \"committed\"` instead writes the\nconfigured reviewed file for cross-machine synchronization. The committed seed\ninitializes local state in a fresh clone.\n\nFor resources named `port:`, `copse list` and `copse doctor` also show\nthe listening process PID and working directory when `lsof` is available.\n\n## Development\n\n```sh\nnpm test # unit and real-Git integration tests\nnpm run check # syntax-check every module\nnpm run test:coverage # coverage report\nnpm run test:package # packed consumer plus deterministic two-agent acceptance\n```\n\nThe packed acceptance launches fixture `codex` and `claude` commands in two\nconcurrent feature worktrees; it exercises isolation and leases without using\nvendor authentication or quota. Authenticated vendor acceptance is deliberately\nopt-in and is never run by ordinary `copse verify`:\n\n```sh\nCOPSE_LIVE_AGENT_TEST=1 \\\nCOPSE_CODEX_COMMAND='[\"codex\"]' \\\nCOPSE_CLAUDE_COMMAND='[\"claude\"]' \\\nnpm run test:agents:live\n```\n\nThe live command can consume Codex and Claude quota. Each command variable must\nbe a non-empty JSON argv array; review the vendors' project-hook trust prompts.\n\nThe CI matrix runs Node 20, 22, and 24, cancels superseded runs, uses\nleast-privilege permissions, runs the full local `copse verify` path, records\ncoverage, and smoke-tests the package. Architecture and contribution rules are\nin [CONTRIBUTING.md](CONTRIBUTING.md); the trust model is in\n[SECURITY.md](SECURITY.md).\n","readmeFilename":"README.md"}