Skip to main content
     ██╗  █████╗  ██████╗  ███╗   ██╗
     ██║ ██╔══██╗ ██╔══██╗ ████╗  ██║
     ██║ ███████║ ██████╔╝ ██╔██╗ ██║
██   ██║ ██╔══██║ ██╔══██╗ ██║╚██╗██║
╚█████╔╝ ██║  ██║ ██║  ██║ ██║ ╚████║
 ╚════╝  ╚═╝  ╚═╝ ╚═╝  ╚═╝ ╚═╝  ╚═══╝

J.A.R.N. — Just A Reliable Nerd

A TUI-first coding agent harness built on DeepAgents.

English · ภาษาไทย

jarn demo


J.A.R.N. is a terminal coding agent in the spirit of Claude Code and Codex CLI, but built as its own opinionated harness on top of the DeepAgents library. Its defining trait is reliability: it plans before acting, can enforce project verification, and asks before doing anything risky. With verify.gate: auto, a failed acceptance command triggers one bounded repair attempt and blocks successful completion if it still fails.

It runs entirely in your terminal (a Web UI is on the roadmap, post-launch). Notable capabilities: AGENTS.md / CLAUDE.md interop (works out-of-the-box beside other agents), headless one-shot mode (jarn -p "..."), JSONL session transcripts, ! shell escape (output fed into the next agent turn as context), OS-level execution sandbox (macOS sandbox-exec / Linux bwrap) and Docker container backend (execution.backend: docker), presets (/preset, jarn --preset) that set mode + sandbox at once, with an untrusted floor, auto-checkpoint + /undo / /redo, repo map (/map), a wiki knowledge base (/wiki), /config settings panel (interactive tabbed UI, persists to ~/.jarn/config.yaml), and per-server MCP health (/mcp status).

Status: v0.9.2 (Alpha) — on PyPI (pip install jarn) and npm (npm install -g jarn-cli — a standalone binary, no Python). v0.9 is a hardening release: a full self-improvement audit plus adversarial multi-model review (47 repro-verified fixes across permissions, cost integrity, concurrency, compaction, and observability; MCP tools are now namespaced mcp__<server>__<tool> — see CHANGELOG for the breaking note). The three releases before it (v0.6.0–v0.8.0) landed four improvement waves: engine reliability; UX parity with Claude Code (live in-place streaming, /theme, @git:/@url: mentions, word-level diffs, ghost autosuggest, conversation /rewind with file restore); differentiators (--add-dir multi-root, inline images, headless --output-schema, labelled subagent streaming, pluggable web search, an LSP-lite diagnostics loop, a verified-completion badge); and launch systems (a reusable GitHub Action + a nightly eval harness). The architecture, configuration, permission engine, and terminal REPL are implemented and tested; live model calls require your own API key. See CHANGELOG.md and SECURITY.md.

Security: J.A.R.N. runs tools on your host by default (real filesystem + shell). A project's .jarn/config.yaml can declare hooks, MCP servers, and provider overrides — only trust repositories you would run code from. Untrusted projects are gated until you approve (jarn trust). Read SECURITY.md before use.

Why J.A.R.N.?

  • Reliable by design — plan → act → verify is baked into the system prompt. The default verify.gate: suggest shows the detected acceptance command; opt-in verify.gate: auto runs it before completion. The completion badge — ⎿ verified: pytest ✓ 214 passed · 3.2s — confirms the result. A failure is fed back for a bounded repair round and, if still failing, ends the turn/headless run as an error instead of success. A diagnostics feedback loop (LSP-lite) then lints/type-checks just the files each turn edited (ruff + pyright) and can queue one bounded auto-fix round, so the agent catches the type error it just introduced (verify.diagnostics: auto).
  • Safe by default — a multi-layer permission system (coarse modes + fine-grained rules) sits in front of every file write and shell command, backed by a hard danger-guard that always confirms catastrophic actions — even in YOLO mode.
  • Bring your own model — 13 providers (OpenRouter, Anthropic, OpenAI, Google, Mistral, Groq, DeepSeek, Together, Fireworks, xAI, Ollama, LM Studio, plus a generic OpenAI-compatible endpoint) with per-task routing so subagents can use cheaper models.
  • Labelled subagent streaming — output from delegated task subagents is tagged with a dim ┊ <name> prefix and collapses to a single └ <name>: working… (N tool calls) status line (full text in the Ctrl+O pager), so parallel subagents no longer interleave anonymously.
  • Cost- & context-aware — live token/cost tracking (with a per-tool breakdown) and a per-session budget that can warn or hard-stop; a context-% gauge and live generation throughput (tok/s) that work for local models (LM Studio / Ollama) too, not just priced cloud ones.
  • Date-aware — the current local date/time is injected into the system prompt, so "today"-relative requests don't anchor to the model's training cutoff.
  • Pluggable web search — web_search supports Tavily, Brave Search, and Exa in addition to the keyless DuckDuckGo fallback. Set search.provider: auto (default) and export TAVILY_API_KEY / BRAVE_API_KEY / EXA_API_KEY — the first one set wins.
  • Extensible — skills, slash commands, custom subagents, lifecycle hooks, and MCP servers, all configured through plain files in ~/.jarn and .jarn/.

Install

macOS (Apple Silicon) and Linux (x64 / arm64) are supported; on Windows use WSL.

Via npm — a self-contained binary, no Python required:

npm install -g jarn-cli     # installs the `jarn` command (also available as `jarn-cli`)

Intel macs install via pip/uv instead (no npm binary is published for them).

Via pip / uv — requires Python 3.12+ and uv:

pip install jarn            # PyPI (alpha)
# or: uv tool install jarn

From source:

git clone https://github.com/chayapats/jarn && cd jarn
uv sync --extra dev
uv run jarn

uv.lock is tracked in the repo so every teammate gets the same dependency versions.

Sharing with your team

git clone <repo-url> && cd jarn
uv sync --extra dev
uv run jarn setup          # once per machine — stores API key in ~/.jarn
cd your-project
jarn doctor                # config, providers, and loaded extensions
jarn                       # trust prompt appears if the project declares hooks/MCP
jarn trust .               # pre-approve a repo you control (optional)

If a cloned project ships .jarn/config.yaml with hooks, MCP servers, or provider overrides, J.A.R.N. asks before honouring them. Decline to run safely with those settings stripped, or run jarn trust <path> after reviewing the repo. Use jarn doctor to see which skills, commands, subagents, hooks, and MCP servers would load (including shadowed or skipped files).

Uninstall

To fully remove all J.A.R.N. state (config, secrets, trust store, sessions) and OS keychain entries:

jarn uninstall          # shows an itemized summary, then prompts for confirmation
jarn uninstall --yes    # skip the prompt

jarn uninstall removes only ~/.jarn (global state) — it never touches project-local .jarn/ directories. After removal it prints the package-manager uninstall line (npm uninstall -g jarn-cli or pip uninstall jarn).

Quick start

With OpenRouter (recommended — one browser click, no manual key handling):

jarn login        # opens browser → authorize → key stored in OS keychain
cd your-project
jarn              # launch the TUI (runs setup if still needed)

Or configure manually:

jarn setup        # first-run wizard: pick a provider, store your API key, choose defaults
cd your-project
jarn init         # create a JARN.md project-context file (optional but recommended)
jarn              # launch the TUI
jarn doctor       # diagnose config / providers / keys / extensions at any time
jarn bug          # assemble a redacted report + open a prefilled GitHub issue

Shell completions (tab-complete subcommands and flags):

# zsh — run once, then restart your shell
jarn completions zsh > ~/.zfunc/_jarn
# add to ~/.zshrc if not already: fpath=(~/.zfunc $fpath) && autoload -Uz compinit && compinit

# bash — run once, then source or restart
jarn completions bash > ~/.bash_completions/jarn.bash
# add to ~/.bashrc: source ~/.bash_completions/jarn.bash

# fish — run once
jarn completions fish > ~/.config/fish/completions/jarn.fish

On first launch with no config, J.A.R.N. runs the setup wizard automatically. The OpenRouter option in the wizard also offers a one-click browser login.

Non-interactive / scripting

jarn -p "summarise the open TODOs"          # one-shot: print reply and exit
echo "what changed?" | jarn -p -            # read prompt from stdin
jarn -p "do X" --json                        # emit JSON: {result, tokens, cost, turns}
jarn -p "do X" --model anthropic/claude-opus-4-8  # override model for this run
jarn -p "do X" --permission-mode auto-edit  # allow file writes without prompting
jarn -p "do X" --cwd /path/to/project       # set working directory
jarn -p "extract the version" --output-schema schema.json --json  # structured output

Structured output (--output-schema): pass a JSON Schema file to constrain the agent's final answer. The parsed object replaces the free-text result field in the --json envelope, making CI parsing trivial:

jarn -p "list changed files as JSON" --output-schema files.schema.json --json \
  | jq '.result.files[]'

Exit codes when --output-schema is used: 0 success (structured object in result); 1 with error.kind: "schema" if the agent fails to produce a conforming response; 2 with error.kind: "usage" if the schema file can't be read or parsed.

Fail-closed safety: the default modes (ask / plan) refuse any tool that would normally prompt for approval and exit non-zero. Pass --permission-mode auto-edit or yolo to allow unattended tool use — the danger-guard still blocks catastrophic commands in every mode.

In CI

J.A.R.N. ships a GitHub Actions composite action so you can run it in any workflow — PR review, issue-fix bots, nightly audits.

- uses: chayapats/jarn/action@main
  with:
    prompt: "Review this diff: …"
    preset: "review-only"     # read-only; use 'ci' for write-enabled runs
    max_turns: "5"
    api_key: ${{ secrets.OPENROUTER_API_KEY }}

Outputs: result, cost_usd, turns.

Docker note: the default ci preset requires Docker (ubuntu runners have it). For docker-less runners (macOS/Windows) use preset: trusted-repo with permission_mode: auto-edit — see docs/GITHUB_ACTION.md.

Example workflows: PR review bot · Issue-fix bot. Full docs: docs/GITHUB_ACTION.md.

The interface: native inline

jarn            # start a session
jarn --resume   # pick a previous session to resume on launch
jarn --add-dir ../shared-lib --add-dir ../sibling-repo  # extra writable roots (repeatable)

Multi-root workspaces (--add-dir): by default the agent's write scope is the project root. Pass --add-dir <dir> (repeatable) to grant scoped write access to a sibling directory too — useful for monorepo/sibling-repo work. Each dir must exist and be a directory. The launch flag works for headless runs too (`jarn -p … --add-dir

`). You can also add one mid-session with `/add-dir

Metadata

Release files for jarn 0.9.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jarn 0.9.2
File Size Uploaded Provenance Actions
jarn-0.9.2.tar.gz 747.7 kB With provenance Details for jarn-0.9.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jarn 0.9.2
File Interpreter ABI Platform Actions
jarn-0.9.2-py3-none-any.whl Python 3 none any Details for jarn-0.9.2-py3-none-any.whl

Total release size: 1.3 MB

Release files / jarn-0.9.2.tar.gz

Download URL jarn-0.9.2.tar.gz
Size 747.7 kB
Tags Source
SHA-256 checksum
How to use checksums
11e1712b4ac077fd4da4d93cec9765d89f4735e2282d1a3415352db6de7a6250
BLAKE2b-256 checksum
How to use checksums
113ad5a363b8cb8ad176b7a37ec6ccdb716e7a07d641fb274dfcaada5bfda252
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 4, 2026.

Transparency log

Release files / jarn-0.9.2-py3-none-any.whl

Download URL jarn-0.9.2-py3-none-any.whl
Size 514.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3e4a793ee363eb74a2b7a48073863bc80f10a1647a8df1f134d04951baa0cc4c
BLAKE2b-256 checksum
How to use checksums
099584054166d4f3cab5d5819c3371d3d0392183458a874335b890b4afa45894
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 4, 2026.

Transparency log

Security for jarn 0.9.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for jarn-0.9.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page