██╗ █████╗ ██████╗ ███╗ ██╗
██║ ██╔══██╗ ██╔══██╗ ████╗ ██║
██║ ███████║ ██████╔╝ ██╔██╗ ██║
██ ██║ ██╔══██║ ██╔══██╗ ██║╚██╗██║
╚█████╔╝ ██║ ██║ ██║ ██║ ██║ ╚████║
╚════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═══╝
J.A.R.N. — Just A Reliable Nerd
A TUI-first coding agent harness built on DeepAgents.
English · ภาษาไทย
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, verifies its own work, asks before doing anything risky, and never claims success on a guess.
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.5.0 (Alpha) — on PyPI (
pip install jarn) and npm (npm install -g jarn-cli— a standalone binary, no Python). Closes five user pain points vs other harnesses (prompt caching, plan-mode handoff,/commit+/review, background processes, macOS image paste) plus a UX-polish round (live in-place streaming, conversation/rewind, rich@-mentions, in-session/key, faster approvals). 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.yamlcan 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, with a self-verification loop that runs your project's build/test/lint before reporting done.
- 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.
- 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.
- Extensible — skills, slash commands, custom subagents, lifecycle hooks, and MCP
servers, all configured through plain files in
~/.jarnand.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).
Quick start
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
On first launch with no config, J.A.R.N. runs the setup wizard automatically.
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
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.
The interface: native inline
jarn # start a session
jarn --resume # pick a previous session to resume on launch
J.A.R.N. renders the conversation straight to your terminal's normal buffer — no alternate screen. The whole transcript lives in your terminal's native scrollback: one scroll gesture scrolls everything and native selection/copy works across the entire history, exactly like Claude Code. Assistant replies stream live and render as Markdown; tool calls, approvals, and a per-turn diff preview appear inline.
Using J.A.R.N.
┌ toolbar: model · mode · queue · ctx · cost ─────────────────────────────┐
│ │
│ conversation stream (assistant output, tool calls, approvals) │
│ │
├────────────────────────────────────────────────────────────────────────┤
│ › your message… │
└────────────────────────────────────────────────────────────────────────┘
- Type a message and press Enter to send (Shift+Enter / Ctrl+J for a newline).
- Start a line with
/for a command (see below).@references a file path or a rich mention:@<path>— file or directory (default; bare@).@folder:<frag>— directories only.@symbol:<name>— repo-map symbol (function / class).@git:status|diff|staged|log— on submit, replaced by a fenced block of real read-only git output (--porcelain=v1 -b,diff,diff --staged,log --oneline -15). Fixed argv allowlist, no shell, 5 s timeout. Output is secret-redacted before injection.@url:<url>— rewrites tofetch <url> with web_fetch and use its contentat submit time; no pre-fetch (network stays agent-mediated and SSRF-guarded).
- ↑ / ↓ navigate input history.
- Tab accepts the highlighted completion (
/commandor@file). Completion uses a two-tier fuzzy engine: exact-prefix matches appear first (unchanged predictability), followed by subsequence fuzzy matches — so/cmitfinds/commitand@pyprjctfindspyproject.toml. - Ghost autosuggest: as you type, the most recent matching history entry appears as dim ghost text after the cursor (fish/zsh-style). Press → (Right arrow) or Ctrl+E at the end of the line to accept the full suggestion. The ghost is hidden while the completion dropdown is open; Right arrow navigates normally mid-line.
- Ctrl+R opens a reverse-history picker: an arrow-key overlay over the 50 most recent unique history entries with live type-to-filter. Press ↑/↓ to navigate, Enter to prefill the input (does not submit), Esc to cancel. Works even while a turn is running.
- Shift+Tab cycles the permission mode (plan → ask → auto-edit → yolo); the new mode flashes on the input border and stays in the status bar.
- Ctrl+O (or
/expand) opens the last turn's full tool output in the pager. - Ctrl+V pastes an image/screenshot from the clipboard — it's saved under
.jarn/pastes/and inserted as an@paththe agent reads on send. Supported on macOS (PNG/TIFF/JPEG), Linux (Waylandwl-pasteor X11xclip), and Windows (PowerShell); images over 10 MB are rejected. - Esc Esc (two Esc presses within 500 ms, idle, empty input) opens the
/rewindpicker — same chord as Claude Code. The first Esc still clears non-empty input; only the second Esc on an already-empty buffer fires the picker. - Esc cancels the running turn. Ctrl+C cancels a turn / clears the input, and twice in a row exits (Claude Code-style). Ctrl+Q also quits.
- Copy text: the terminal owns selection — just drag to select and ⌘C (or your terminal's copy), and scroll with your terminal's native scrollback, exactly like Claude Code.
- Notifications: when a turn takes longer than
ui.notify_min_secs(default 10 s), jarn emits a terminal bell (\a). Setui.notify: desktopfor a native OS notification (macOS / Linux),bothfor bell + desktop, oroffto silence all notifications. Approval prompts always ring regardless of elapsed time. - Terminal tab title: jarn sets the terminal-tab title via OSC 2 to show the current
state —
jarn — <project>(idle),✳ jarn — <project>(working),⏸ jarn — <project>(waiting for approval). Setui.terminal_title: falseto disable. - Live plan checklist: when the agent plans, a
⏺ Todoschecklist appears above the input and updates in place as items flip (✔ done / ◐ in progress / ☐ pending), Claude Code-style, with the streaming reply below it. A long plan is capped (overflow collapses to… +N more); the full list is committed to scrollback at turn end.
Assistant replies render as Markdown (headings, lists, syntax-highlighted code).
/model, /mode, and /resume with no argument open an arrow-key picker
(↑/↓ + Enter; Esc cancel). /model also offers a custom ref prompt.
While a turn is running, submitted lines are queued (shown in the toolbar as
queue N); manage them with /queue, /queue clear, /queue cancel <n>, or
/queue move <from> <to>.
Built-in commands
| Command | Description |
|---|---|
/help |
Show available commands and shortcuts. |
/init |
Create a JARN.md project context file. |
/config |
View or edit settings: /config, /config get , /config set (persists). |
/model [/ref|refresh] |
Show or switch the active model; /model refresh re-queries local endpoints. |
/mode [plan|ask|auto-edit|yolo] |
Show or switch the permission mode (plan/ask/auto-edit/yolo). |
/theme [dark|light|high-contrast|auto] |
Show or switch the color theme (dark/light/high-contrast/auto). |
/sandbox [on|off] |
Show or toggle the execution backend (local/sandbox). |
/key [<key>] |
Set or replace the API key for the current provider (stored in the keychain). |
/preset [<preset-name>] |
Show or apply a preset — a shortcut that sets mode + sandbox at once. |
/cost |
Show session token usage and cost. |
/compact |
Summarize and compact the conversation context. |
/expand |
Open the last turn's full tool output in the pager (same as Ctrl+O). |
/clear |
Clear the conversation and start a fresh thread. |
/sessions |
List and resume previous sessions. |
/resume |
Pick a previous session to resume. |
/rewind |
Rewind the conversation to an earlier turn and continue (forks a new thread). |
/skills |
List available skills. |
/memory [search|show|add|update|delete|dump] ... |
List, search, show, add, update, delete, or dump long-term memory. |
/permissions |
Show current permission rules and allowlist. |
/mcp [status] [--refresh] |
Show configured MCP servers with per-server health and last error. |
/trust |
Trust this project root and lift the untrusted review-only floor. |
/queue [clear|cancel <n>|move <from> <to>] |
Show or manage queued input lines (while a turn is running). |
/undo |
Revert the last agent turn's file changes. |
/redo |
Re-apply the last undone agent turn's file changes. |
/abort |
Cancel the running turn and roll back its file changes. |
/commit |
Draft a commit message from the current diff and commit (with approval). |
/review |
Review the current working-tree diff for bugs and quality (read-only). |
/checkpoints |
List recent auto-checkpoints. |
/ps [kill <id>] |
List or kill background processes (from run_in_background). |
/quit |
Exit J.A.R.N. |
/map [focus] [--refresh] |
Show the ranked repo map (codebase overview). |
/wiki [search <q>|list] |
Search or list wiki knowledge-base pages. |
/doctor |
Diagnose configuration, providers, and keys. |
/telemetry status |
Show telemetry opt-in status and local sink stats. |
Permission modes
| Mode | File reads | File writes | Shell | Network |
|---|---|---|---|---|
plan |
✅ | ❌ | ❌ | ❌ |
ask (default) |
✅ | ask | ask | ask |
auto-edit |
✅ | ✅ in-scope | ask | ✅ (read-only) |
yolo |
✅ | ✅ | ✅ | ✅ |
In plan mode the agent researches read-only, then presents a concrete plan
(exit_plan_mode). Approve it and J.A.R.N. escalates the mode (default auto-edit,
configurable via plan.exit_mode; the picker also offers ask) and carries the plan
out in the same turn — no manual mode switch. Untrusted projects stay clamped to plan.
The danger-guard overrides all modes: rm -rf (incl. rm -r -f / --recursive --force), force-push, git reset --hard, mkfs, fork bombs, out-of-scope writes, etc.
always require explicit confirmation (or are blocked outright). Esc/Ctrl+C cancels a
turn and kills any shell it spawned. See docs/PERMISSIONS.md.
Untrusted repos: a project's .jarn/config.yaml can declare hooks, MCP servers, and
providers — capabilities that can run code or read secrets. J.A.R.N. asks you to trust
a project before honoring those keys (once per repo); decline and they're ignored while
the session continues safely.
Configuration
Two tiers, both YAML, merged together (project overrides global):
~/.jarn/config.yaml global: providers, keys (by reference), defaults, budget
.jarn/config.yaml per-project: MCP servers, hooks, permission rules (committed)
JARN.md per-project context, auto-loaded into the system prompt
API keys are referenced, never inlined — ${ENV_VAR} or keychain:jarn/<provider>.
Project config is gated by a trust prompt (see above). See
docs/CONFIGURATION.md for the full reference.
Extending
Drop files into ~/.jarn/{skills,commands,agents} (global) or .jarn/{...} (project):
- Skills (
skills/*.md) — reusable knowledge/workflows, auto- or manually-triggered. - Commands (
commands/*.md) — custom/slashprompt templates. - Subagents (
agents/*.md) — specialist agents the main loop can delegate to. - Hooks (config) — shell commands run on lifecycle events (lint after edit, test before commit).
- MCP servers (config) — connect external tool servers (stdio or HTTP).
See docs/EXTENDING.md (quick start) and examples/.
Documentation
- Architecture — how the subsystems fit together
- Configuration — every config key explained
- Permissions — modes, rules, danger-guard, approvals
- Extending — skills, commands, subagents, hooks, MCP
- Contributing — dev setup, tests, conventions
- Roadmap — what's in v1 / v1.x and what's next
- Web UI — planned, post-launch design
- Open-core — licensing & business model
- SPEC.md — the original design specification
Troubleshooting
Esc Esc rewind feels slow or doesn't register
Terminals encode many keys as ESC-prefixed byte sequences (e.g. arrow keys start
with \x1b[). To tell a lone Esc from the start of a sequence, prompt_toolkit
waits a short time (~100 ms) after seeing \x1b before delivering it as a bare
Esc keystroke. This is inherent to how terminals work — not a jarn bug — and means
the Esc-Esc chord has a slight delay on the first press. The 500 ms window is
generous enough that a normal double-tap still registers.
If the chord never fires, check that neither the terminal nor tmux/screen is
eating the second \x1b (some multiplexers bind Esc for their own prefix key).
Terminal ignores OSC 2 title updates
Some terminal emulators do not support OSC 2 (\x1b]2;…\x07) or suppress it by default.
jarn's tab-title feature is silently no-op in those environments — no visible side-effect
occurs. If you see stray escape characters in your output, set ui.terminal_title: false
in ~/.jarn/config.yaml to disable the feature entirely.
Caps Lock inserts a stray a (macOS)
On macOS, when Caps Lock is set to switch input source, some terminal apps that
enable the Kitty keyboard protocol's report-all-keys mode can leak a stray a
into the input. J.A.R.N. disables those flags for Textual (onboarding wizard,
jarn keys) and resets any leftover kitty flags before the main REPL starts
(prompt_toolkit does not enable report-all-keys itself).
- Run
jarn keys(Textual) orjarn keys --repl(prompt_toolkit) to see exactly what your terminal sends for each key — share a line with a maintainer if you hit an unfiltered quirk. - Set
JARN_KEEP_KITTY_ALL_KEYS=1to opt out of the fix if you rely on full kitty key reporting (e.g. for a custom key-binding workflow).
Development
uv sync --extra dev
uv run pytest # 1504 tests: logic + mocked-agent + packaging gate
uv run ruff check src tests scripts # lint
uv run mypy src/ # type-check (CI-gated)
uv run jarn doctor # sanity-check your environment (add --json for machine output)
License
Apache-2.0. See LICENSE.
Built on DeepAgents, LangGraph, prompt_toolkit, Rich, and Textual (onboarding wizard only).
Metadata
Release files for jarn 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jarn-0.6.0.tar.gz | 520.8 kB | With provenance | Details for jarn-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jarn-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for jarn-0.6.0-py3-none-any.whl |
Total release size: 866.5 kB
Release files / jarn-0.6.0.tar.gz
| Download URL | jarn-0.6.0.tar.gz |
|---|---|
| Size | 520.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1f3f187cd436cf7e01fd40be9358afc3a950f201dc9ace48fe5af6b0d83a2f25
|
|
BLAKE2b-256 checksum How to use checksums |
b41809b561dd898f4b9d2a59d10b5f6953427ca5be1c332a7500e43a9f01c97f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Jul 7, 2026.
Transparency logRelease files / jarn-0.6.0-py3-none-any.whl
| Download URL | jarn-0.6.0-py3-none-any.whl |
|---|---|
| Size | 345.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
03915bdcad684abee036a5967b0f06a9017aad5c35ab1a4d02d0b6843d8a0934
|
|
BLAKE2b-256 checksum How to use checksums |
4a3eb098c28bed2e34762d4c040d7749c4ba11a8f8c9da3538693e1ff492402c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Jul 7, 2026.
Transparency logSecurity for jarn 0.6.0
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.
Attestation for jarn-0.6.0.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 Jul 7, 2026.
Transparency logA 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.