NEEDLE

1. Install needle, its transform helpers, and the bead-rs backend.

cargo install --git https://github.com/jedarden/NEEDLE

cargo install --git https://github.com/jedarden/bead-rs --bin bead

```

The installer drops binaries in ~/.local/bin (override with NEEDLE_INSTALL_PATH). An existing bead at or above the release version is kept.

📋 Step 3: Build

Construct the prompt from the bead's context: title, body, workspace path, relevant files, and any dependency context. The prompt is a deterministic function of the bead state — same bead, same prompt.

🚀 Quickstart

Prerequisites: git, tmux, and an agent CLI on your PATH — the flow below uses Claude Code (claude). Prebuilt binaries are Linux x86_64; everything else builds from source (see below).

```bash

~/.config/needle/config.yaml

worker: enforce_shipped_work: false

**Built-in validation gate for unguarded workspaces:** A workspace whose own
`.needle.yaml` declares neither `gates:` nor legacy `verification:` enters the
no-explicit-gate path. An explicit `gates: []` or `verification: []` remains an
opt-out. NEEDLE first lets the language-default resolver supply a `default_*`
gate; only when it supplies none does the shipped **interim fallback gate**
select a verifier from the committed workspace, in this exact order:

1. `scripts/definition-of-done.sh` — run `scripts/definition-of-done.sh`.
2. `go.mod` — run `go build ./... && go vet ./... && go test -short ./...`.
3. `Cargo.toml` — run `cargo build --all-targets && cargo test`.
4. `package.json` with a non-empty `scripts.test` — run `npm test`.
5. `pyproject.toml` — run `pytest -q`.
6. `pytest.ini` — run `pytest -q`.

The selected command runs in a clean `git archive HEAD` extraction, so it
judges committed state rather than the shared checkout. If no verifier is
selected, NEEDLE checks the source workspace with
`git status --porcelain --untracked-files=all` (the archive has no `.git`),
ignoring `.beads/` and `.needle-predispatch-sha` bookkeeping noise. A clean
status passes on the agent's exit code alone and emits one counted `WARN`,
`gate.no_verifier`, with reason `not_detected`; uncommitted work fails the
fallback gate. Extraction, spawn, and timeout failures are gate execution
errors; a non-zero verifier result is an ordinary verification failure.

Fallback command stderr is capped by the host setting
`validation.stderr_cap_bytes` (default `4096` bytes), and each command is
bounded by `validation.outcome_timeout_seconds` (default `50` seconds). The
fallback is armed by default, so every unguarded workspace without an
override is covered without a per-workspace config change; the rollout count
is only an inventory snapshot, not a hard-coded allowlist. When fallback
resolution is reached, the dispatch log records whether it is armed or opted
out. A workspace can explicitly opt out in its own `.needle.yaml`:

The host-level `validation.fallback_gate` sets the default and the workspace
value wins. This fallback is the **INTERIM** mechanism. The
`needle-d1b2ee0d` runner is its planned replacement. A workspace-local
`scripts/definition-of-done.sh` is the hand-off for repositories that already
declare their own Definition of Done; that runner is intended to replace this
fallback gate rather than add another permanent gate layer.

**Build from source** (Rust 1.95+, the toolchain pinned in `rust-toolchain.toml`) — from the canonical Forgejo remotes, or from the read-only GitHub mirror by swapping the hostname:

Optional features

• Attempt archive — optional per-attempt transcript, trace, and exact-prompt bundles written to a local spool; disabled by default and never requires ARMOR or another upload sink. See docs/attempt-archive.md.

---

🔌 claude-interactive Plugin

The claude-interactive plugin ships as a separate release asset. It wraps the Claude Code CLI in a PTY so workers run under your Claude subscription instead of consuming programmatic API credits.

How it works: NEEDLE pipes subprocess stdio, which causes claude to detect a non-TTY and switch to API billing. claude-interactive creates an internal PTY so claude sees a real terminal, keeping it in interactive/subscription mode.

Prerequisites: - Python 3.10 or later - pyte Python library (installed automatically by the installer, or manually via pip install pyte) - The claude CLI on PATH

Install:

```bash

The workflow for a new repository

1. Push-to-create. Forgejo auto-creates the repo on first push — no manual repo-creation step, no POST /api/v1/user/repos:

   cd <repo-dir>
   git branch -m main                     # git init defaults to master
   git remote add origin https://git.ardenone.com/jedarden/<repo>.git
   git push -u origin main                # auto-creates the repo
   

---