Picagear

A local code factory for one developer and one repository.

Picagear takes a large epic, proposes a capacity-safe weekly commitment, asks for one approval, compiles each approved task into a strict work order, and then runs one task per pull request through Codex and Claude Code in isolated git worktrees. It verifies fresh artifacts and declared gates itself instead of trusting a worker's exit status, retries once in a fresh worktree when a run produces nothing, and blocks with evidence when that fails. A terminal dashboard shows the line as an assembly line.

Picagear runs locally, requires no Picagear service to receive repository content, and sends work only through the coding providers the user has configured. It is not a chat application, a hosted development environment, or a project manager.

Status

Picagear 0.1.0-next.0 is a preview published to npm under the next tag. It is a functional foreground command line tool. It never merges a pull request and it never deletes a worktree. A full lifecycle system integration run against the installed package and live task performance with real providers are not yet proven.

Install and initialize

Picagear requires Node 22.13 or later, Git, and the provider CLIs you enable. Install the preview as a development dependency of a private consumer project with package scripts disabled, then run the installed bin. A source checkout does not link its own bin, so this path does not exist there.

cd <consumer-directory>
npm init --yes
npm pkg set private=true --json
npm install --save-dev --ignore-scripts picagear@next
./node_modules/.bin/picagear --help
./node_modules/.bin/picagear init --repo <path> --adapters codex,claude

A reviewed local archive remains a supported alternative. The installation guide covers both paths. Decadra advisory integration is optional and installed separately from a reviewed local archive. The Decadra package currently published on npm does not provide that integration.

Factory data lives under PICAGEAR_HOME. The default is ~/.picagear. The global --home <dir> option takes precedence over the environment variable.

Commands select the factory for the Git repository containing the current directory. Use the global --factory <id> option to select one explicitly. Outside a repository, Picagear refuses an ambiguous home containing more than one factory and lists the available identifiers.

Set PICAGEAR_ADAPTERS=fake before running commands for a quota-free pilot. This keeps Git real but replaces provider execution, pull request creation, and Decadra with deterministic fakes. With no PICAGEAR_FAKE_SCRIPT, fake execution produces no artifact, which exercises the retry and block path.

Add an epic

Save an epic request as epic.json. Each backlog entry becomes a task brief at intake.

{
  "schemaVersion": 1,
  "id": "epic-config-validation",
  "title": "Validate project configuration",
  "objective": "Reject invalid project configuration with clear local diagnostics.",
  "constraints": ["Keep configuration parsing offline."],
  "horizonDays": 7,
  "backlog": [
    {
      "id": "validate-config",
      "title": "Add configuration validation",
      "outcome": "Create a bounded configuration validator and tests for missing required fields.",
      "category": "build",
      "tier": "standard",
      "priority": 80,
      "dependsOn": [],
      "allowedPaths": ["src/app", "test"],
      "prohibitedPaths": ["src/adapters"],
      "expectedArtifacts": [
        { "path": "src/app/config.ts", "kind": "created", "required": true },
        { "path": "test/config.test.ts", "kind": "created", "required": true }
      ],
      "gates": ["test"],
      "verification": [["npm", "test", "--", "test/config.test.ts"]],
      "completionEvidence": ["Invalid configuration is rejected and the focused test passes."],
      "contextRefs": ["src/app"],
      "estimatedMinutes": 120,
      "reviewBurden": 1,
      "ambiguity": 0,
      "blastRadius": 0,
      "reversibility": 2,
      "gateStrength": 2,
      "interpretation": "strict",
      "requestedTools": ["read", "edit", "write", "grep"],
      "requestedPermissions": ["read", "edit", "write", "run-gates"],
      "needsBrowser": false,
      "needsVisual": false
    }
  ],
  "references": ["README.md"],
  "completionDefinition": "The validator is independently verified and ready for review."
}

picagear epic add epic.json

A supplied backlog is normalized as written. An epic with an empty backlog is decomposed by objective sentences into at most eight reviewable implementation slices. Each slice is bounded to one charter allowed root and the mandatory charter gates. Intake only proposes briefs. It cannot execute before plan approval. Epic constraints are copied into every normalized brief and compiled work order.

Plan and approve once

plan proposes a capacity-safe weekly subset. Capacity allowances are attempt counts kept separately for each adapter. Provider-native units are never converted or summed. Inspect the proposal before giving the single approval that creates the active commitment. Approval binds the hash of every included brief.

picagear plan
picagear plan show
picagear plan approve

Use picagear plan approve --remove <task-id> to remove a task before approval. Use --plan <id> to approve a specific proposal.

Compile and run

The first scheduling tick compiles committed briefs into strict work orders pinned to the current base revision. A dependent brief waits until each prerequisite is complete and integrated, then compiles against a base that contains those revisions. Later ticks dispatch, verify, retry, or block work. A tick that dispatches an attempt waits for that attempt to finish because Picagear has no daemon. Both tick and run hold the coordinator lock, so a competing tick exits with status 4.

picagear tick
picagear tick
picagear tick

Use the foreground supervisor when you want repeated ticks.

picagear run

picagear run --max-ticks 10 bounds a foreground run. In another terminal, watch the event log projection.

picagear dashboard --watch 5
picagear inspect validate-config
picagear work-order show validate-config

After Picagear has independently verified an attempt, open its pull request and record the review decision. Pull request creation requires retained artifact observations for the exact attempt and order, a changed tree inside scope, the current work order hash, and a passed result for every mandatory gate and verification command. Picagear pushes the immutable verified revision and confirms the remote branch head. Existing pull requests for the attempt branch are reconciled before a new one is created.

picagear pr open validate-config
picagear approve validate-config
picagear archive validate-config

Use picagear reject validate-config --reason "Tests need a narrower fixture" instead of approval when review fails. Archiving is allowed only after completion.

Control and diagnose

Pause prevents new dispatch while allowing verification to continue. Resume restores dispatch. Stop records cancellation requests for active attempts and keeps every worktree.

picagear pause --reason "Review queue is full"
picagear resume
picagear stop --reason "End the current run"
picagear doctor

Use picagear status for a compact projection. Use picagear retry <task> only for a blocked task that is eligible for manual retry. A compile failure, worker mismatch, or rejected review can use a replacement brief. Save a complete corrected TaskBriefV1 object with the same task and epic identifiers, then run the following commands. The replacement remains pending until its explicit approval, and a new plan approval is still required.

picagear brief replace validate-config corrected-brief.json
picagear brief approve <proposal-id>
picagear plan
picagear plan approve

Documentation

Read the architecture overview, data file reference, compiler diagnostics, work order contract, execution adapter reference, privacy boundary, testing guide, decisions, and delivery plan.

Development

npm install
npm run check
node dist/cli.js doctor

Read AGENTS.md before changing code.

License

Picagear is licensed under the PolyForm Strict License 1.0.0. It permits use for noncommercial purposes as the license defines them. It does not grant rights to distribute the software or to make changes or new works based on it. Public availability on npm does not grant further rights. Read the license text for the full terms.