██╗ █████╗ ██████╗ ███╗ ██╗
██║ ██╔══██╗ ██╔══██╗ ████╗ ██║
██║ ███████║ ██████╔╝ ██╔██╗ ██║
██ ██║ ██╔══██║ ██╔══██╗ ██║╚██╗██║
╚█████╔╝ ██║ ██║ ██║ ██║ ██║ ╚████║
╚════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═══╝
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, 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: this source line targets v1.0.11 General Availability. Publication is controlled by automated gates, protected UAT, and strict evidence; consult the GitHub Releases, PyPI, and npm pages for the currently published version. v0.10 adds an optional single-operator Telegram gateway: long-poll DM control, isolated per-root workers, durable approval cards, inbound media, scheduling, and VPS/systemd deployment. Earlier releases landed engine reliability; UX parity with Claude Code (live in-place streaming,
/theme,@git:/@url:mentions, word-level diffs, ghost autosuggest, conversation/rewindwith file restore); differentiators (--add-dirmulti-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.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 without prompt micromanagement — a small outcome-and-safety kernel
leaves the model free to adapt its workflow to the task. The default
verify.gate: suggestshows the detected acceptance command; opt-inverify.gate: autoruns 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.
- Instruction-aware — project context and skills guide only the user's stated goal. Source files, web pages, logs, and tool results are treated as data, so embedded instructions cannot override user intent or the harness's permission, trust, and sandbox boundaries. The agent uses only tools exposed by the active policy and backend.
- Bring your own model — 15 providers, including Codex through your ChatGPT subscription, OpenRouter, OpenCode, Anthropic, OpenAI, Google, Mistral, Groq, DeepSeek, Together, Fireworks, xAI, Ollama, LM Studio, and a generic OpenAI-compatible endpoint, with per-task routing so subagents can use cheaper models.
- Labelled subagent streaming — output from delegated
tasksubagents 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.
- Observable prompt modules — only the 146-word reliability/safety kernel is
unconditional. Plan guidance, trusted project context, memory/skill/wiki catalogs,
repo maps, the date, and explicitly loaded skill bodies are activated when relevant,
budget-capped, and manageable through an interactive
/modulespicker with short explanations./modules activeretains the detailed scope, source, token, and truncation report. - Date-aware — the current local date is injected once per thread/day, so "today"-relative requests don't anchor to the model's training cutoff.
- Pluggable web search —
web_searchsupports Tavily, Brave Search, and Exa in addition to the keyless DuckDuckGo fallback. Setsearch.provider: auto(default) and exportTAVILY_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
~/.jarnand.jarn/.
Install
macOS (Apple Silicon) and Linux (x64 / arm64) are supported; on Windows use WSL.
Recommended — one-command installer:
jarn_installer_tmp=$(mktemp "${TMPDIR:-/tmp}/jarn-install.XXXXXX") && trap '[ -z "${jarn_installer_tmp:-}" ] || rm -f "$jarn_installer_tmp"' 0 HUP INT TERM && curl -fsSL 'https://raw.githubusercontent.com/chayapats/jarn/main/install.sh' -o "$jarn_installer_tmp" && sh "$jarn_installer_tmp"; jarn_install_rc=$?; [ -z "${jarn_installer_tmp:-}" ] || rm -f "$jarn_installer_tmp"; trap - 0 HUP INT TERM; if [ "$jarn_install_rc" -eq 0 ] || [ "$jarn_install_rc" -eq 10 ]; then exec "$SHELL" -l; else (exit "$jarn_install_rc"); fi
The command first downloads the installer to a private temporary file, so a failed
download is never executed. The installer inventories old jarn commands, detects
the OS/CPU/libc, verifies the release checksum, stages and smoke-tests the candidate,
activates it transactionally, and verifies what a fresh shell resolves. If a native
binary cannot run (for example because of older GLIBC), it uses an isolated managed
Python fallback. The final exec solves the parent-shell PATH limitation; status
10 means installation is verified but shell activation was still required, and
status 20 means setup remains incomplete.
The installer can acquire a compatible official standalone Codex dependency during ChatGPT setup after showing its source, version, purpose, destination, and integrity checks. No separate Node/npm/Python/Codex preparation is required on the standard path. See the five-minute quickstart.
Advanced installation alternatives
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 --extra telegram
uv run jarn
uv.lock is tracked in the repo so every teammate gets the same dependency versions.
Package-manager installs retain package-manager ownership; use that manager to update/remove them unless J.A.R.N. presents and you confirm an explicit migration.
Sharing with your team
git clone <repo-url> && cd jarn
uv sync --extra dev --extra telegram
uv run jarn setup # once per machine — stores only a keychain/env/file reference in config
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
Removal is itemized and preserves user data by default:
jarn uninstall # choose categories interactively
jarn uninstall --yes # remove only the managed executable
jarn uninstall --sessions --cache # confirm only those two categories
jarn uninstall --credentials --yes # explicitly remove J.A.R.N. credentials
Categories are executable, exclusively owned dependencies, configuration, sessions,
cache/logs/telemetry, and credentials. Shared Node, Python, uv, and Codex installs
are never removed. Project-local .jarn/ directories are never touched. See
Update, rollback, and uninstall.
Quick start
With a ChatGPT/Codex subscription (no OpenAI API key billing):
jarn setup # choose “Continue with ChatGPT”
# Setup offers a verified Codex dependency install when needed, then shows login.
jarn auth status # verifies dependency, auth mode, plan/workspace
cd your-project && jarn
J.A.R.N. talks to the official local Codex App Server; it never reads or stores
ChatGPT OAuth tokens. Codex's own execution surfaces are disabled in this provider,
and requested tools are translated back into ordinary J.A.R.N. tool calls so the
existing permission, danger-guard, checkpoint, and /undo paths remain authoritative.
Subscription usage is shown as tokens with $0 API cost and still consumes the
limits/credits of your ChatGPT plan. For shared CI, use an API-key provider instead.
With OpenRouter OAuth (separate, advanced credential command):
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 # write a privacy-scanned report; ask before opening GitHub
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.
Transactional setup accepts an environment reference or an in-memory pasted key;
it deliberately does not run OpenRouter OAuth because that exchange persists a key
before final confirmation. Run jarn login separately when OAuth is desired.
Telegram gateway (optional)
v0.10 adds a single-operator, DM-only gateway for an always-on VPS. The npm binary includes it; Python installs need the optional extra:
pip install 'jarn[telegram]' # omit for the standalone/npm distribution
jarn gateway setup
The wizard verifies the token with Telegram, asks you to send /start to the bot,
discovers and confirms your numeric user ID, stores the token in the OS keychain
(owner-only file fallback), updates the global config transactionally, and on Linux
offers an owner-scoped systemd service. No token or hand-edited YAML is required.
Use jarn gateway status afterward. Advanced repo allowlisting and manual service
deployment remain documented in the Telegram gateway guide;
never put gateway: in a project's .jarn/config.yaml.
Non-interactive / scripting
jarn exec "summarise the open TODOs" # recommended discoverable form
jarn exec --json "what changed?" # one machine-readable JSON result
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
jarn exec and the shorter legacy jarn -p spelling use the same execution,
permission, output, and exit-code contract.
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);
9 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
Metadata
Release files for jarn 1.0.11
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-1.0.11.tar.gz | 1.3 MB | With provenance | Details for jarn-1.0.11.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jarn-1.0.11-py3-none-any.whl | Python 3 | none | any | Details for jarn-1.0.11-py3-none-any.whl |
Total release size: 2.2 MB
Release files / jarn-1.0.11.tar.gz
| Download URL | jarn-1.0.11.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f410ac1f854cd1139e8d3a189649016a380d5667dc2c0cc3b16b85e0ba0a13cc
|
|
BLAKE2b-256 checksum How to use checksums |
2db01f0ba89e93988147d78d445cc2b4d5b45a8ae81b880dafad2aa0e3293c61
|
| 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 21, 2026.
Transparency logRelease files / jarn-1.0.11-py3-none-any.whl
| Download URL | jarn-1.0.11-py3-none-any.whl |
|---|---|
| Size | 882.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e3b06bb7388a0e5d055f0f2dc60c8c32724fae386a871a041a9531c80f70c504
|
|
BLAKE2b-256 checksum How to use checksums |
fe5f88d1a8c650b10544be479baf8a151e1db87deccb78e69aabe93cafa69a35
|
| 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 21, 2026.
Transparency logSecurity for jarn 1.0.11
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-1.0.11.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 21, 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.