{"_id":"@0spoon/projd","name":"@0spoon/projd","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.3":{"name":"@0spoon/projd","version":"0.1.3","description":"Project harness for long-running and parallel AI agent sessions with Claude Code","license":"MIT","repository":{"type":"git","url":"git+https://github.com/0spoon/projd.git"},"bin":{"projd":"bin/projd.js"},"engines":{"node":">=18"},"type":"module","keywords":["claude","claude-code","ai","agent","project-management","parallel-agents"],"gitHead":"2fbf97000a3c8f0f192f435b5811fdca34dd03a5","_id":"@0spoon/projd@0.1.3","bugs":{"url":"https://github.com/0spoon/projd/issues"},"homepage":"https://github.com/0spoon/projd#readme","_nodeVersion":"23.9.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-ipKnxZ8Rdo2Wvaz4ize3qO6k4crqQn/byXsILKHYex/IKL8Mtf+4tTNaCFvP3a1Vr3wmFCaafRoEMQexVuShdA==","shasum":"99371b122822dd4672bb28dd3b9355f96eb8ae47","tarball":"https://registry.npmjs.org/@0spoon/projd/-/projd-0.1.3.tgz","fileCount":7,"unpackedSize":62427,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC7GVy9/bjkYZHfVdBqY0m9zISij1dl1k0pEXAvQQsh6gIgND5GZv4tjdbXQk7QMGm2IVWansRXqcJiBkv/zGaoSMU="}]},"_npmUser":{"name":"0x3k","email":"eitan@3174.org"},"directories":{},"maintainers":[{"name":"0x3k","email":"eitan@3174.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/projd_0.1.3_1775940604206_0.27012422154342364"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-11T20:50:04.148Z","0.1.3":"2026-04-11T20:50:04.362Z","modified":"2026-04-11T20:50:04.556Z"},"maintainers":[{"name":"0x3k","email":"eitan@3174.org"}],"description":"Project harness for long-running and parallel AI agent sessions with Claude Code","homepage":"https://github.com/0spoon/projd#readme","keywords":["claude","claude-code","ai","agent","project-management","parallel-agents"],"repository":{"type":"git","url":"git+https://github.com/0spoon/projd.git"},"bugs":{"url":"https://github.com/0spoon/projd/issues"},"license":"MIT","readme":"# projd\n\n[![npm version](https://img.shields.io/npm/v/@0spoon/projd)](https://www.npmjs.com/package/@0spoon/projd)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Built for Claude Code](https://img.shields.io/badge/Built_for-Claude_Code-6B5CE7)](https://claude.ai/code)\n\n**Project Daemon** -- pronounced \"prodigy\" `/ˈprɒdɪdʒi/` by some. We don't correct them.\n\n> A project harness for long-running and parallel AI agent sessions. You describe what you want, projd breaks it into features, and Claude builds them -- one at a time or several in parallel. You review PRs. That's the whole deal.\n\nClaude Code works great in a single sitting. But when sessions get long or you want multiple agents working at once, things fall apart -- the agent loses context, commits to branches it shouldn't, starts work that conflicts with other agents, and leaves half-finished code behind.\n\nprojd adds the missing pieces: session continuity, git guardrails, a feature lifecycle with dependency tracking, and branch-per-feature isolation so agents don't step on each other.\n\n**What you get:**\n\n- **Feature planning**\n  Break requirements into feature files with acceptance criteria and dependency ordering.\n\n- **Branch-per-feature isolation**\n  Each agent works in its own git worktree. No conflicts.\n\n- **Git policy enforcement**\n  PreToolUse hooks block violations before they execute, not after.\n\n- **Parallel dispatch**\n  Up to 20 agents in dependency-aware waves, with optional auto-review.\n\n- **Session continuity**\n  Structured `.projd/HANDOFF.md` preserves context between sessions.\n\n- **Smoke-test gates**\n  Features aren't marked complete until lint, typecheck, and tests pass.\n\n### What it looks like\n\n```\n$ /projd-plan \"A CLI tool for managing dev environments with Docker\"\n\n  Created 7 features in .projd/progress/:\n    1. config-loader       Parse YAML config with validation and defaults\n    2. env-lifecycle       Create, start, stop, destroy environments\n    3. docker-backend      Docker container management (blocked by: config-loader)\n    4. template-engine     Project templates with variable substitution (blocked by: config-loader)\n    5. port-forwarding     Automatic port mapping and conflict detection (blocked by: docker-backend)\n    6. shell-completions   Bash/zsh/fish completions (blocked by: env-lifecycle)\n    7. status-dashboard    Live TUI showing running environments (blocked by: docker-backend)\n\n$ /projd-hands-off --dry-run\n\n  Dispatch plan (max_agents: 20):\n    Wave 1: config-loader, env-lifecycle                        (2 agents)\n    Wave 2: docker-backend, template-engine, shell-completions  (3 agents)\n    Wave 3: port-forwarding, status-dashboard                   (2 agents)\n\n  7 features, 3 waves. Run without --dry-run to start.\n\n$ /projd-hands-off\n\n  Dispatching wave 1...\n    [config-loader]  worktree created   branch: agent/config-loader\n    [env-lifecycle]  worktree created   branch: agent/env-lifecycle\n\n  Wave 1 complete. Dispatching wave 2...\n    [docker-backend]     worktree created   branch: agent/docker-backend\n    [template-engine]    worktree created   branch: agent/template-engine\n    [shell-completions]  worktree created   branch: agent/shell-completions\n\n  Wave 2 complete. Dispatching wave 3...\n    [port-forwarding]    worktree created   branch: agent/port-forwarding\n    [status-dashboard]   worktree created   branch: agent/status-dashboard\n\n  7/7 features complete. 7 PRs ready for review.\n```\n\nRun `./.projd/scripts/monitor.sh` in a second terminal for a live dashboard -- progress bars, per-feature token tracking, and keyboard shortcuts to act on features directly. See [Parallel Agents](docs/parallel-agents.md) for details.\n\n---\n\n### When to use projd\n\n| Scenario | Why projd helps |\n|----------|----------------|\n| **Greenfield build from a spec** | You have requirements. projd decomposes them into features, builds them in parallel, and you review PRs. A weekend project that would take a week of sequential sessions. |\n| **Adding a major capability to an existing app** | `/projd-adopt` + `/projd-plan`. The dependency graph ensures new features build on each other correctly. Agents can't break what's already working because smoke tests gate completion. |\n| **Batch of independent improvements** | 8 features on your backlog, none depend on each other. `/projd-hands-off` builds all 8 in parallel. You merge the PRs. |\n| **Multi-service monorepo** | `projects.json` gives each service its own progress tracker. Agents work across services in parallel without conflicts. |\n\nprojd is overkill for single-feature bug fixes, quick scripts, or exploratory \"I don't know what I want yet\" sessions. Just use Claude Code directly for those.\n\n---\n\n### Quick Start\n\n**Prerequisites:**\n\n| Tool | Install |\n|------|---------|\n| [Claude Code](https://claude.ai/code) | See [claude.ai/code](https://claude.ai/code) |\n| [Lefthook](https://github.com/evilmartians/lefthook) | `brew install lefthook` |\n| [jq](https://jqlang.github.io/jq/) | `brew install jq` |\n| [gh](https://cli.github.com/) | `brew install gh` |\n\nFull guide: [Setup](docs/setup.md)\n\n**Install with npm/pnpm** (from anywhere):\n\n```bash\nnpx @0spoon/projd\n# or\npnpm dlx @0spoon/projd\n```\n\n**Or with curl** (from anywhere):\n\n```bash\nbash <(curl -fsSL https://raw.githubusercontent.com/0spoon/projd/main/.projd/scripts/remote-install.sh)\n```\n\n**Or from a local clone:**\n\n```bash\n./.projd/scripts/install-skill.sh\n```\n\nThis installs `/projd-create` and `/projd-adopt` to `~/.claude/skills/`. Skills auto-update once per day when invoked.\n\n```\n/projd-create                 # scaffold a new project from any Claude Code session\n/projd-adopt                  # add projd to an existing project\n/projd-plan \"your idea\"       # break it into features\n/projd-hands-on               # build one feature at a time\n/projd-hands-off              # or launch parallel agents\n```\n\n**Next steps:** Check the PRs it created. Read [Features](docs/features.md) for the feature file format, and [Agent Controls](docs/agent-controls.md) to tune git policy and dispatch behavior.\n\n### Adding projd to an existing project\n\nAlready have a working codebase? Use `/projd-adopt` instead of `/projd-create`:\n\n```\ncd your-existing-project\n/projd-adopt\n```\n\nThe skill copies infrastructure files (skills, hooks, scripts), merges your existing `.claude/settings.json` and `CLAUDE.md` non-destructively, creates `.projd/agent.json`, and sets up the `.projd/progress/` directory. It supports both developer and vibes modes. See [Setup](docs/setup.md) for details.\n\n### How it works\n\n```\n  /projd-plan \"requirements\"\n          |\n          v\n  .projd/progress/*.json (feature files)\n          |\n    +-----+------+\n    |            |\nhands-on    hands-off\n    |            |\n    v            v\n 1 agent    N agents\n you watch   in parallel\n    |            |\n    v            v\n   PRs         PRs\n    |            |\n    +-----+------+\n          |\n    +-----+------+\n    |            |\nyou review   reviewer agent\n  + merge    (vibes mode)\n    |            |\n    +-----+------+\n          |\n     /projd-plan (repeat)\n```\n\n**Hands-on** -- you stay in the loop with one agent. You pick a feature, the agent implements it, you review the PR and start the next one. Good for when you want to steer.\n\n**Hands-off** -- agents work in parallel, you review at the end:\n\n```\n  YOU             DISPATCHER           AGENTS\n   |                  |                  |\n   |  /projd-hands-off|                  |\n   |----------------->|                  |\n   |                  |  wave 1          |\n   |                  |----------------->|  agent/feature-a (worktree)\n   |                  |----------------->|  agent/feature-b (worktree)\n   |                  |                  |\n   |                  |  blockers done   |\n   |                  |  wave 2          |\n   |                  |----------------->|  agent/feature-c (worktree)\n   |                  |                  |\n   |    PRs ready     |                  |\n   |<-----------------|                  |\n   |                  |                  |\n   |  review + merge  |                  |\n```\n\n**Hands-off with vibes mode** (`auto_review: true`) -- fully autonomous. A reviewer agent checks each PR, fixes issues, and merges passing ones without you:\n\n```\n  YOU             DISPATCHER           AGENTS            REVIEWER\n   |                  |                  |                  |\n   |  /projd-hands-off|                  |                  |\n   |----------------->|                  |                  |\n   |                  |  wave 1          |                  |\n   |                  |----------------->|  feature-a       |\n   |                  |----------------->|  feature-b       |\n   |                  |                  |                  |\n   |                  |    PR ready      |                  |\n   |                  |                  |----------------->|\n   |                  |                  |   smoke tests    |\n   |                  |                  |   check criteria |\n   |                  |                  |                  |\n   |                  |                  |   pass? merge    |\n   |                  |                  |<-- auto-merged --|\n   |                  |                  |                  |\n   |                  |                  |   fail? fix+retry|\n   |                  |                  |   still fail?    |\n   |  flagged for you |                  |   flag for human |\n   |<----------------------------------------------------- |\n   |                  |                  |                  |\n   |                  |  wave 2 begins   |                  |\n   |                  |  (blockers merged)|                 |\n   |                  |----------------->|  feature-c       |\n```\n\nSet `\"auto_review\": true` in `.projd/agent.json` to enable vibes mode. The reviewer runs smoke tests, verifies acceptance criteria, and merges passing PRs. If it finds issues, it fixes trivial ones inline and spawns a subagent for larger fixes. PRs that still fail after fixes are flagged for manual review.\n\nEach agent reads `.projd/HANDOFF.md` for prior context, implements against acceptance criteria, runs smoke tests, and creates a PR. `/projd-plan` again when new work comes in.\n\n<details>\n<summary><strong>Docs</strong></summary>\n\n| Topic | Link |\n|-------|------|\n| Setup | [docs/setup.md](docs/setup.md) |\n| Skills | [docs/skills.md](docs/skills.md) |\n| Features | [docs/features.md](docs/features.md) |\n| Agent Controls | [docs/agent-controls.md](docs/agent-controls.md) |\n| Parallel Agents | [docs/parallel-agents.md](docs/parallel-agents.md) |\n| Hooks | [docs/hooks.md](docs/hooks.md) |\n| Multi-Project | [docs/multi-project.md](docs/multi-project.md) |\n| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |\n| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |\n\n</details>\n\n---\n\n## What's Included\n\n| Path | Purpose |\n|------|---------|\n| `CLAUDE.md` | Project knowledge: overview, build commands, architecture, conventions |\n| `.claude/CLAUDE.md` | projd workflow: agent controls, session protocol, feature lifecycle |\n| `.projd/agent.json` | Git policy and dispatch config (branch protection, push control, parallel limits) |\n| `.projd/progress/` | Per-feature tracking files with acceptance criteria, dependencies, and status |\n| `.projd/scripts/` | Setup, validation, smoke tests, monitoring, status line, environment bootstrap |\n| `.claude/hooks/` | Git policy enforcement (PreToolUse hook blocks violations before they execute) |\n| `.claude/skills/` | The projd skill family: plan, hands-on, hands-off, create, adopt, start, end |\n| `lefthook.yml` | Pre-commit hooks (lint + typecheck) and pre-push guard |\n| `setup.sh` | Interactive wizard to configure language, project details, and team/solo mode |\n\n## Parallel Agents\n\n`/projd-hands-off` dispatches parallel agents on independent features. Each gets its own git worktree and branch.\n\n```\n.projd/progress/*.json\n      |\n      v\n  +-----------+     +----------------+     +-----------+\n  | Wave 1    |     | Wave 2         |     | Wave 3    |\n  +-----------+     +----------------+     +-----------+\n  | config    | --> | docker-backend | --> | port-fwd  |\n  | env-life  |     | template-eng   |     | status-ui |\n  |           |     | completions    |     |           |\n  +-----------+     +----------------+     +-----------+\n      |                   |                     |\n      v                   v                     v\n  2 PRs              3 PRs                 2 PRs\n```\n\nFeatures with `blocked_by` dependencies are scheduled in waves -- each wave starts only after its blockers complete.\n\nWith **vibes mode** (`\"auto_review\": true` in `.projd/agent.json`), the loop closes itself -- a reviewer agent checks each PR, fixes what it can, and merges passing ones automatically. You only get pulled in when something fails twice.\n\n> [!TIP]\n> Use `--dry-run` to preview dispatch order before committing to a run.\n\nSee [Parallel Agents](docs/parallel-agents.md) for the full dispatch protocol, monitor dashboard, and configuration options.\n\n## Monorepo / Multi-Project\n\nAdd a `projects.json` at the root and each sub-project becomes its own projd instance -- own `CLAUDE.md`, `.projd/progress/`, and `.projd/scripts/`. Agents work across sub-projects in parallel, and root-level features handle cross-cutting work.\n\n```\n  projects.json\n       |\n       +-- services/api/          (own CLAUDE.md, .projd/progress/, .projd/scripts/)\n       |     +-- feature-a  -->  agent in worktree\n       |     +-- feature-b  -->  agent in worktree\n       |\n       +-- services/worker/       (own CLAUDE.md, .projd/progress/, .projd/scripts/)\n       |     +-- feature-c  -->  agent in worktree\n       |\n       +-- root .projd/progress/  (cross-cutting features)\n             +-- feature-d  -->  agent in worktree\n```\n\nRoot scripts (`status.sh`, `smoke.sh`, `init.sh`) automatically aggregate across all sub-projects. See [Multi-Project](docs/multi-project.md) for setup details.\n\n## Landscape\n\n**projd is a project template, not a platform.** You clone it, configure it once, and the structure lives inside your repo alongside your code. Nothing to install globally, no daemon, no desktop app. The trade-off: it's opinionated about Claude Code and doesn't support other agents.\n\nWhat projd does that most alternatives don't:\n\n| Capability | How |\n|------------|-----|\n| **Git policy enforcement** | PreToolUse hook intercepts commands before they execute -- the agent cannot bypass branch protection |\n| **Session continuity** | Structured `.projd/HANDOFF.md` preserves context between sessions instead of relying on chat history |\n| **Dependency-aware dispatch** | Features declare `blocked_by` dependencies; the dispatcher schedules waves and won't start blocked work |\n| **Smoke-test gates** | A feature isn't complete until lint, typecheck, and tests pass -- enforced by the skill, not judgment |\n\nSee [Landscape](docs/landscape.md) for a detailed comparison with Spec Kit, Agent Orchestrator, Kagan, Emdash, Claude Squad, dmux, Plandex, and others.\n\n---\n\nBased on patterns from [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). MIT License -- see [LICENSE](LICENSE).\n","readmeFilename":"README.md","_rev":"1-5cff0e6cbb5716ac54e7c14a299e6da9"}