NEEDLE

NEEDLE is an open-source Rust-based agent orchestration harness and execution framework developed by Jed Arden. It provides structured execution loops, modular agent strands, and validation gates for running AI coding agents against codebases. At runtime, NEEDLE executes workflows through specialized sub-agents—such as WeaveAgent, ReflectAgent, and UnravelAgent—configured through a `.needle.yaml` specification. The orchestrator isolates test environments, dispatches tasks, and coordinates multi-step development actions while tracking execution lifecycle events. NEEDLE distinguishes itself from standard CLI chat wrappers by emphasizing strict quality gates and deep observability. It incorporates a unified definition-of-done system across pre-commit hooks, CI, and agent execution runs, complete with bypass tracking and OpenTelemetry (OTLP) resource reporting for host and process-level metrics. NEEDLE is published as an open-source project on GitHub under active development, written in Rust for minimal overhead in local and containerized CI environments.

Tags: agent harness, ai agent, cli, developer tools, OpenSource

Visit NEEDLE

Key features

• Modular strand agents — Implements specialized agents including WeaveAgent, ReflectAgent, and UnravelAgent for distinct phases of coding and reflection. - Unified definition-of-done gating — Configures dual-lane validation (fast lane for fmt/clippy and slow lane for test suites) defined via .needle.yaml and hook scripts. - OTLP and JSONL telemetry — Streams process and host-level telemetry events to standard output, JSONL logs, or OTLP collectors. - Bypass tracking — Automatically records validation bypasses to .beads/bypasses.jsonl to maintain auditability of skipped checks. - Workspace and environment isolation — Pins workspace roots and isolates user home directories to prevent test pollution during agent operations.

Use cases

Use Case: Automated Definition-of-Done Enforcement Developers can integrate NEEDLE into local pre-commit workflows or CI pipelines to run AI coding tasks that must pass strict formatting, linting, and unit test suites before committing.

Use Case: Observable Agent Orchestration Teams managing automated code generation can stream OTLP telemetry to monitor agent processes, execution durations, and step completion across multi-agent workflows.

Use Case: Isolated Code Refactoring Engineers can task specialized sub-agents with multi-file refactoring runs within isolated workspace boundaries to prevent unintended side effects on user environment state.

Who it is for

NEEDLE is suited for Rust developers, platform engineers, and teams building observable, automated coding harnesses that require strict validation gates. It is not intended for non-technical users seeking a simple conversational chatbot UI.

Install guide

Installation Install NEEDLE from source using Cargo (standard Rust installation method): bash cargo install --git https://github.com/jedarden/NEEDLE.git

First Run Set up your workspace configuration by creating a .needle.yaml file in the root of your project to declare validation rules: yaml # .needle.yaml validation: fast_lane: "cargo check && cargo clippy" slow_lane: "cargo test" Ensure your LLM provider credentials (such as ANTHROPIC_API_KEY) are exported in your environment: bash export ANTHROPIC_API_KEY="your-api-key"

Example Session Trigger an agent task using the NEEDLE CLI: bash needle run "Refactor the strand module to export ReflectAgent and verify fast lane gates"

Part of CLI Coding Agents

Categories: AI Coding Agents, Code Assistants, Developer Tools

Related CLI agents

• SWE-agent — SWE-agent is an open-source autonomous software engineering agent harness built and maintained by researchers from Princeton University and Stanford University.…
• Agentic Engineering Framework — Agentic Engineering Framework is an open-source orchestration harness and governance layer developed by Dimitri Geelen. It is designed to constrain,…
• Hivelore — Hivelore is an open-source agent harness and contextual memory orchestrator created by Doucs91. It provides persistent project memory, decision tracking,…
• Weaver — Weaver is an open-source agent harness and orchestration framework maintained by sean35mm on GitHub. Built on top of the Bun…
• Stratless — Stratless is an open-source agent harness and execution orchestrator developed by the Stratless AI team. It provides a modular infrastructure…
• Context Bridge — Context Bridge is an open-source CLI agent harness and context orchestration utility developed by serdardb. It is built to facilitate…