pi-495

Pi-495 is a Pi extension that turns a software request into a change you can inspect, verify and integrate. It coordinates the AI work, defines how success will be checked before implementation, and runs those checks on the result. You review the changes and resolve decisions that need human judgment.

Use it to add behavior, fix a bug or refactor a supported project with an explicit record of what was requested, what changed and why it was accepted.

/495 start add a retry with backoff to the upload client

The core rule: the checks are frozen before implementation. The coding agent cannot change the protected tests or decide that its own work is accepted.

Available today: an early implementation for macOS on Apple Silicon and for Linux (tested on arm64), with Java/Maven and Node adapters. Models come from your Pi configuration. Start with a small change on a project whose tests already run locally.

• Pi is the host. Pi is a minimal terminal coding harness that packages extend without forking it. It brings what 495 does not rebuild: the models you configure and authenticate, the agent session each intervention runs in, the terminal dialogues where you answer decisions, and the TUI, RPC, JSON and print modes. 495 is a Pi package, with no CLI or service of its own.
• 495 is the three-digit Kaprekar constant: repeated application of a simple rule reaches a fixed point for eligible starting numbers. The name reflects the project's use of explicit rules and feedback to drive a change toward acceptance. Explore the number.

Quick start

You need Node.js 24+, Pi 1.0.4 or later, Git, and either macOS on Apple Silicon or Linux (tested on arm64) with bubblewrap (bwrap) on PATH, able to create its namespaces without privilege. Your target project must have at least one Git commit and use a supported test setup. Install its dependencies before starting: verification runs with restricted network access.

1. Install the extension

From npm:

pi install npm:pi-495

Pi installs the package and its dependencies under its own npm directory. pi update npm:pi-495 moves it to the latest release; install npm:pi-495@0.4.0 instead to pin a version.

From the Git repository, in a directory where you keep your tools:

git clone https://github.com/jeanjerome/pi-495.git
cd pi-495
npm ci
npm run build
pi install "$PWD"

Pi registers this local directory. Keep it in place; after updating the source, reinstall dependencies and rebuild it.

Install from one source only, so that a single copy of the extension loads.

2. Start a change in your project

cd /path/to/your-project
pi

Configure and authenticate your model in Pi, select it with /model, then enter:

/495 start add a retry with backoff to the upload client

495 advances through Scoping, Specification, Qualification, Design, Implementation and Acceptance. It stops when it needs a decision or cannot proceed, and records the reason.

To survey the project instead of changing it, enter /495 state followed by a question about the project, for example /495 state does the code meet its quality standards?. 495 runs the checks on the project as it stands, writes no candidate, and asks you to accept or refuse the survey.

Integration is disabled by default. To allow it, set policy.integration_enabled to true before starting a new session. After acceptance, /495 integrate requests local integration and any required authorization. 495 does not push to a remote repository.

Features

How it works

Define success → freeze the checks → produce a candidate → judge the evidence.

flowchart TD
    S["`**Scoping**
the objective and the questions it raises`"] --> SP["`**Specification**
requirements with observable criteria`"]
    SP --> Q["`**Qualification**
checks qualified, verification protocol frozen`"]
    Q --> D["`**Design**
the plan within the mandate`"]
    D --> I["`**Implementation**
a candidate in an isolated workspace`"]
    I --> A{"`**Acceptance**
does the evidence satisfy the protocol?`"}
    A -->|"Yes"| G["`**Integration**
the accepted candidate applied locally, when authorized`"]
    A -->|"Correction within budget"| I
    A -->|"Decision or capability missing"| X["Stop and record the next action"]

Agents propose artifacts and code. The kernel runs the controls and applies the acceptance rules. Required agent reviews and human decisions are additional inputs when the protocol calls for them. /495 verify reruns the frozen controls without calling a model.

Acceptance establishes conformance to the adopted protocol, within the limits of its controls and reviews.

Compatibility

A recorded qualification case reached acceptance with one local model and one hosted model. It covers a small contract case; the record also notes that the two runs used different harness builds. It is not a qualification of every model or project shape.

• Selecting a model in Pi admits its provider; 495 keeps no list of destinations of its own. The model worker needs network access; tools and controls have their own confinement profiles.
• Model qualification can issue a small tool-call probe, cached per provider/model pair for the session. A hosted provider may bill that request.
• Budget controls currently cover attempts, time, continuations and tool calls; they are not a monetary spending cap.
• export --redact masks recognized secret patterns. Review a dossier before sharing it; pattern matching does not guarantee that every sensitive value was removed.
• The offline verifier checks dossier integrity and event-chain consistency. It does not rerun the target's checks or prove that every requirement is correct.

Roadmap

The direction is a broader engineering workflow: understand an existing codebase, strengthen its verification, and guide changes with traceable decisions. These capabilities are planned or deferred; they are not all available in the current release.

Further qualification and deferred work: additional advanced testing methods such as property-based testing and fuzzing, and indexed documentation retrieval with corpus maintenance. These require further work and qualification; no release date is implied.

See the plan of the open work for the detailed boundaries and progress.

Reference

The conversational harness495 tool can request status, pending decisions, review summaries, reports, verification, export and start. It cannot adopt artifacts, make human decisions or integrate a change.

Configuration and state live outside your project: $HARNESS495_DATA_DIR, otherwise ~/.495. Workspaces default to ~/.495/workspaces; set $HARNESS495_WORKSPACES_DIR to move them.

config.json is optional, and so is each setting in it. The file below holds every behavioural setting at its default value; policy.policy_id and policy.revision only identify the policy. Durations are in milliseconds.

{
  "policy": {
    "budgets": {
      "max_attempts": 3,
      "max_technical_retries": 2,
      "max_continuations": 3,
      "intervention_ms": 1200000,
      "increment_ms": 7200000,
      "tool_calls_per_intervention": 100,
      "feedback_bytes": 65536
    },
    "adoption": {
      "mandate": "kernel",
      "requirements": "kernel",
      "protocol": "kernel",
      "design": "kernel"
    },
    "g5_human_acceptance": false,
    "integration_enabled": false,
    "baseline": {
      "compare_to_reference": true,
      "tolerance": "no_aggravation",
      "instability": "confirm_then_indeterminate",
      "max_confirmations": 1
    },
    "stagnation_identical_candidates": 2,
    "required_reviews": []
  },
  "isolation": { "allow_unconfined": false },
  "human_origin": { "rpc_actor_env": "HARNESS495_RPC_HUMAN_ACTOR" },
  "workspace_exclusions": ["target/", "dist/", ".pi/", "__pycache__/", "build/", "node_modules/.vite/", "node_modules/.vite-temp/", "node_modules/.vitest/", "reports/mutation/", ".stryker-tmp/"],
  "language": "fr"
}

config.json must match its schema. A file that does not, that is not valid JSON, that cannot be opened or that is not a regular file stops every /495 command, /495 help included, and the error says what is wrong: for a file that does not match, where its first three deviations lie and what is expected there, and how many others there are. The defaults never replace it, since one of its settings may keep a decision for a human. Fix the file, then reload Pi (/reload) or start a new session.

HARNESS495_INTEGRATION=1, HARNESS495_HUMAN_ACCEPTANCE=1 and HARNESS495_LANGUAGE=en override the file. Set them before starting Pi.

Contributing

Early feedback is especially useful on real Maven and Node projects: the request, the command used, the observed stop reason and the expected behavior help make a report actionable. Ask questions and suggest ideas in Discussions; report defects with a bug report.

CONTRIBUTING.md explains how to build, check and propose a change. Report a vulnerability privately, as the security policy describes. Everyone who takes part follows the code of conduct.

License

Apache License 2.0 © 2026 Jean-Jerome Levy.