Prjct App Cli

prjct-cli

The agentic harness for AI coding agents. Intelligence is rented, the harness is owned: prjct-cli gives Claude Code, Codex, Gemini, Cursor, OpenCode, and any agent intent briefs, bounded RAG context, preventive guardrails, synthesized learning, and performance signals for each dev+LLM work cycle.

[](https://www.npmjs.com/package/prjct-cli) [](./LICENSE) []() []() []()

Install / upgrade — one paste

Copy this prompt and paste it in Claude Code (works for fresh install AND upgrade — Claude picks YOUR package manager, doesn't force npm):

Install or upgrade prjct-cli on this machine. First detect which package manager I use globally (check `command -v pnpm`, `command -v bun`, `command -v yarn`, `command -v npm` in that order; also check where any existing `prjct` install lives via `command -v prjct` and use the SAME package manager so we don't create parallel installs). Then run the matching install:
- pnpm: `pnpm install -g prjct-cli@latest`
- bun:  `bun install -g prjct-cli@latest`
- yarn: `yarn global add prjct-cli@latest`
- npm:  `npm install -g prjct-cli@latest`

After install, run `prjct install` to verify/repair required native dependencies and hooks, then `prjct setup` to wire providers, then `prjct sync` if the cwd is a git repo. Verify with `prjct -v` and tell me which package manager you used.

~30 seconds. Claude detects YOUR package manager (pnpm, bun, yarn, npm) and uses it — critical so we don't end up with parallel installs in different package managers' bin dirs. Re-pasting upgrades to the latest published version.

> Why detection matters: if you have pnpm globally and Claude runs npm install -g prjct-cli@latest, you end up with TWO installs in PATH. The earlier one wins, prjct -v reports the wrong version, and aggressive cleanup risks bricking your shell. The detection-first prompt avoids this entirely.

Prefer no Node/npm? (run in your own terminal)

If you'd rather have the standalone binary (Bun runtime embedded, no Node ecosystem needed), run this yourself in a terminal — it's a curl | bash install which Claude Code's harness intentionally blocks for safety:

curl -sSL https://raw.githubusercontent.com/prjct-app/cli/main/scripts/install-standalone.sh | bash

The script auto-detects platform (mac arm64/intel + linux x64), downloads the right binary from GitHub Releases, sets up ~/.local/bin/prjct on your PATH, runs prjct setup + prjct sync, and warns you if a stale package-manager install is shadowing the new binary.

Updating prjct-cli (built-in)

prjct-cli updates itself. The canonical command is prjct update, with prjct upgrade as an identical alias:

prjct update            # = prjct upgrade
prjct update --dry-run  # show exactly what would change, touch nothing
prjct upgrade --yes     # non-interactive (skip the consolidation prompt)

What it does, in three phases (core/commands/update.ts):

1. Package update — auto-detects the package manager that owns your install

(npm / pnpm / bun / yarn / homebrew), resolves the true registry-latest version and pins it exactly (so a stale @latest cache can't downgrade you), and migrates a homebrew install to your detected PM if needed.

1. Global cleanup & consolidation — migrates legacy state to SQLite,

reinstalls editor commands/config, and consolidates parallel installs so you don't end up with shadowing copies in different PM bin dirs.

1. Daemon restart — stops the stale background daemon and respawns it from

the freshly installed code.

Flags: --dry-run, --yes/-y, --cleanup / --no-cleanup (default auto), --md (machine-readable output for agents/CI).

Knowing an update exists: prjct-cli checks at most once every 24h (cached, fully non-blocking — never delays a command) and, after the command's own output, prints a one-line banner: Update available! x.y.z → a.b.c — Run: prjct upgrade. Or set it and forget it: prjct config set auto-update on (throttled background check, logs to ~/.prjct-cli/state/auto-update.log).

Full install + upgrade paths: [INSTALLPROMPT.md](./INSTALLPROMPT.md).

Platform support

The package-manager install path is the portable path for macOS, Linux, and Windows:

npm install -g prjct-cli@latest
# or pnpm / bun / yarn global install

The daemon uses Unix sockets on macOS/Linux and a Windows named pipe on Windows. Git auto-sync hooks keep the shell wrapper POSIX-small and run rate limiting / background spawn through Node, so they work in Git for Windows without relying on Unix-only utilities like md5sum, stat -f, or date +%s.

The standalone curl | bash installer remains macOS/Linux only. Windows users should use the package-manager install path. CI runs focused platform compatibility smoke tests on Ubuntu, macOS, and Windows.

Zero native dependencies

prjct-cli uses SQLite for local project memory through the runtime's built-in driver — bun:sqlite on Bun, node:sqlite on Node (≥22.5). No native addon, no node-gyp, no postinstall script. It installs cleanly under --ignore-scripts and locked-down CI, which closes the supply-chain surface a native rebuild opens.

What you get

After install, next session in any prjct-cli project:

• Lookup-first protocol: Claude queries prjct (prjct search, prjct context memory, MCP prjct_*) BEFORE re-exploring source. Cuts ~10K tokens of exploration per session.
• Auto-capture: Stop hook scans the assistant transcript and persists durable insights (decisions/learnings/gotchas) tagged for dedup. The next session finds them via recall.
• Pattern detection: Stop hook detects hot files (>3 changes in 7 days), recurring bugs (gotchas with the same topic), tech-debt growth (TODO/FIXME count rising). All persisted as learnings, surfaced next session.
• 6 quality workflows activated by natural language ("review this branch", "qa the UI", "security check", "investigate this bug"):
• review — Production Bug Hunt + Completeness Gate (3 modes)
• qa — Real Browser, Atomic Fixes, Regression Tests
• security — OWASP Top 10 + STRIDE, 8/10 confidence gate, concrete exploit per finding
• investigate — Iron Law (no fix without investigation), max 3 failed hypotheses
• ship (hardened) — Coverage Gate + Auto-Document
• audit — one-shot orchestrator: review + security + investigate combined
• Delivery-geometry advisory (prjct review-risk): reads the committed changeset vs the merge-base and suggests a size tier (trivial/normal/large) + whether to ship direct, as one PR, or split — with the touched top-level dirs as natural split lines. Purely advisory: never gates, never mutates git.
• Session ceremonies: prjct prime restores the full work state at session start; prjct land closes it — hand-off persisted to SQLite plus memory consolidation via prjct dream when its gates open.
• Multi-agent work graph: dependency edges, ready frontier, race-free prjct claim, topological prjct phases — fan several agents out on one cycle without collisions. prjct crew runs the leader / implementers / reviewer flow.
• Code symbol graph: prjct code symbols|trace|impact|architecture|dead — structural code intel built by prjct sync and injected by hooks alongside Grep results.

How it works

State lives in SQLite at ~/.prjct-cli/projects//. prjct is the LLM data plane — agents read it through tools, not files: prjct search, prjct context memory, prjct guard, or the MCP prjct_* tools. There is no generated markdown export to browse or hand-edit.

Claude Code session                       prjct-cli
       |                                    |
       | SessionStart hook fires            |
       | --------------------------------> |  self-heal CLAUDE.md
       |                                    |  (opt-in: silent auto-update check)
       |                                    |
       | Lookup-first protocol kicks in:    |
       | queries prjct before source        |
       v                                    |
  Writes code, makes decisions              |
       |                                    |
       | Stop hook fires                    |
       | --------------------------------> |  scan transcript → memory,
       |                                    |  detect hot files / recurring bugs
       |                                    |  / tech-debt growth → memory

State is the source of truth. New knowledge enters via prjct remember , prjct capture, or — automatically — the Stop hook's transcript scan.

Where data actually lives

Not "all in a local .prjct/ folder" — that's the pre-v1.24.1 model. Two tiers:

| Tier | Location | Commit it? | |---|---|---| | Config / identity | /.prjct/prjct.config.json (projectId, persona) | Yes — small, machine-independent | | State (source of truth) | ~/.prjct-cli/projects//prjct.db (SQLite) | No — per-device |

Find a project's data: read projectId from .prjct/prjct.config.json, then the DB is ~/.prjct-cli/projects// (PRJCT_CLI_HOME relocates the global store). Teammates share knowledge via optional cloud sync (prjct login + prjct sync), not git — git never carries state. Full detail: [docs/storage-and-paths.md](./docs/storage-and-paths.md).

Agent compatibility levels

prjct does not pretend every AI coding agent has the same integration surface. It reports concrete support levels:

| Level | What it means | |---|---| | full | prjct-maintained native hooks plus MCP/skills or equivalent deep integration. | | good | AGENTS.md plus MCP-capable runtime. | | baseline | Repo instructions plus prjct --md; no native hooks assumed. | | hosted | Repo instructions are the portable layer; platform config may be manual. |

Run prjct agents doctor --md to see the current machine/project matrix for Claude Code, Codex, Gemini CLI, OpenCode, Qwen Code, Kimi CLI, Grok Build, Cursor, Windsurf, Cline/Roo-family agents, hosted agents, and future AGENTS.md/MCP clients.

Use prjct agents doctor --fix inside a prjct project to refresh the portable AGENTS.md surface and any repo-local IDE rule adapters prjct manages. The command is idempotent and reports what changed.

Harness intelligence

prjct should justify itself with project evidence, not vague claims. These read-only commands show whether dev+LLM work cycles are getting cheaper, safer, and more precise:

Version evals

Use prjct eval to measure product readiness between versions and publish the evidence to the prjct cloud benchmark API:

prjct eval run --candidate 2.62.0
prjct eval compare --baseline 2.61.0 --candidate 2.62.0 --md
prjct eval run --candidate "$GITHUB_SHA" --publish --target cloud
prjct eval compare --baseline "$BASELINE" --candidate "$CANDIDATE" --publish --target cloud

Local artifacts live under $PRJCT_CLI_HOME/evals//. Cloud publishing requires prjct login and an active prjct cloud link, then sends the benchmark payload to the prjct API with server-side ownership/subscription checks. See [EVALS.md](./EVALS.md) for the full workflow.

| Command | What it proves | |---|---| | prjct insights value --md | Durable memory, preventive guardrails, shipped work, sync metrics, and detected agent coverage. | | prjct insights quality --md | Duplicate, stale, low-signal, or untyped memories before they poison recall. | | prjct insights cost --md | AI work cost: token coverage, subscription burn, context reuse, and capture gaps. | | prjct insights report 7 --md | A human/team report from shipped work and carry-forward lessons. | | prjct insights continue codex --md | A continuation brief for the next agent with checks it should run first. | | prjct insights guardrails --md | File-specific warnings for the current changeset from preventive memory. | | prjct performance 14 --md | Time, tokens, model/runtime, prompt synthesis, tools, outcome, and quality signals per work cycle where available. |

Execution environments (zero-config)

The same binary runs in a plain shell, inside Claude Code, in an OpenAI Codex sandbox, or in CI, and adapts output automatically with no configuration. Detection signals (env vars, MCP, CLAUDE.md, ~/.claude/, the codex binary on PATH, process.stdout.isTTY) are read silently; --md / --json are the only overrides. Full per-environment table, source-file references, and the detection order: [docs/environments.md](./docs/environments.md).

What it looks like

In a real terminal — branded, animated, colored:

$ prjct work "add OAuth refresh"
⚡ prjct  ✓ Work cycle started: add OAuth refresh
         branch: work/add-oauth-refresh · status: active
         harness: H2 feature/medium · evidence: focused-tests, scope-check, spec-or-design

Inside Claude Code / Codex / CI (non-TTY) — the same line, static (no animation), so logs stay clean. With --md, output is plain markdown an agent can consume directly:

$ prjct work "add OAuth refresh" --md
> Work cycle started: **add OAuth refresh**
> branch `work/add-oauth-refresh` · status `active`
> harness `H2 feature/medium` · evidence `focused-tests, scope-check, spec-or-design`

Quick start (post-install)

# In any git repo
prjct sync                                  # register the project (auto on first prjct command)
prjct work "add OAuth refresh"              # start a work cycle
prjct remember decision "we chose JWT + refresh rotation"
prjct remember context "implemented refresh rotation; model/tokens unknown; tests passed"
prjct ship                                  # bump version, commit, push, open PR

In Claude Code, ask naturally:

• "review my changes" → activates the review workflow with Production Bug Hunt methodology
• "what patterns does this project use?" → Claude calls MCP prjct_analysis directly (no grep)
• "investigate why tests intermittently fail" → activates investigate with Iron Law

Optional flags:

prjct config set auto-update on    # silent self-update (1/hour throttled)
prjct team --enforce               # pre-commit hook blocks commits without prjct-cli

Inside Claude Code / Gemini CLI

p. remember context "call Ana re pricing; no work cycle yet"
p. work "add OAuth refresh"                   # start a work cycle
p. remember decision "we chose JWT + refresh rotation"
p. performance 7                              # inspect dev+LLM efficiency
p. ship                                       # commit, push, open PR

Cursor and Windsurf use their installed prjct router files; otherwise run prjct --md and follow the output.

Harness verbs

| Verb | What it does | |---|---| | prjct intent "" | Frame objective, constraints, risks, and success signal before high-stakes work. | | prjct work [""] | Start or inspect a work cycle with context and evidence. | | prjct remember "" | Persist a memory entry (decision, learning, gotcha, …). | | prjct forget | Delete a memory entry by id (prjct forget mem_1234) — the delete half of remember. | | prjct search "" | Search project memory — blended BM25 + semantic + recency recall (prjct search mem_1234 resolves an entry by id). | | prjct guard | Surface preventive memory before editing a risky file. | | prjct performance [days] | Measure dev+LLM efficiency per work cycle. | | prjct insights [value\|quality\|cost\|report\|continue\|guardrails] | Project intelligence, token cost, and quality proof. | | prjct ship [name] | Run the project's ship workflow (commit, push, PR, persist). | | prjct sync | Re-index files, git co-change, imports; refresh project analysis. | | prjct agents doctor | Show the auditable compatibility matrix for local and project agent runtimes. | | prjct review-risk | Advisory change-size + delivery-geometry signal for the branch (read-only

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: prjct-app
• Source: prjct-app/cli
• License: MIT
• Homepage: https://cli.prjct.app

Install and usage instructions live in the source repository linked above.