javis 0.2.0

Joint Autonomous Verified Intelligence System — harness-governed coding agent; intelligence in the harness, not the model

JAVIS — Joint Autonomous Verified Intelligence System

A harness-governed coding agent. The name is the thesis: intelligence is joint — the model is an untrusted prover, the harness a sound proof checker, and neither is the agent alone — and every claim is verified: the gates refuse to advance on anything the tests, parser, or resolver can't confirm. Put the execution intelligence in the harness, not the model. See docs/harness-contract.md.

Created by Okello Solomon Roy Jasper.

Quickstart

git clone https://github.com/Code-weaver1/javis.git && cd javis
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[llm,tui]"

export OPENROUTER_API_KEY=sk-or-...   # any OpenRouter key — free-tier models are enough
javis --check                         # preflight: validates your model ladder against the live catalog
javis --tui --repo /path/to/your/project --task "fix the failing test"

No API key yet? Watch the harness narrate a three-step gated task behind a scripted model — no network, no account:

python scripts/tui_narration_demo.py --delay 0.4

Prefer a guided setup (pick a provider, model, and key interactively)? javis --setup.

Status: v1 — a trustworthy correctness engine

The plan → propose → adjudicate → admit loop with an enforced gate set — 0 (plan-shape), 1 (resolve — rejects hallucinated calls), 2/2b (read-before-write / read-verbatim), 3 (parse), 6 (test), 7 (oracle-integrity — the test oracle is read-only) — plus a tiered router (escalate to a strong tier on failure), a difficulty-graded fixture suite, --sandbox runs, and tier-labeled trajectory logging. Self-planning is off by default (Phase 0 showed it hurts; opt in with --plan).

Honest scope: the harness guarantees correctness — it never ships broken or regressing code, and the oracle can't be gamed — but it does not by itself lift a weak model's completion rate on reasoning-hard tasks (that's the router + distillation). See docs/harness-contract.md §7. Growth still ahead: lint/type gates (4/5), coherence + arch-spec (8), distillation training (P5).

Reliability layer (adapted from Hermes): tool-loop guardrails (halt-and-escalate on thrash), tool-call JSON repair for weak models, a structured API error taxonomy driving router escalation, and a rate-limit cooldown guard so a 429'd model is skipped rather than hammered.

Cost & caching (provider-agnostic). No provider-specific caching code. The loop keeps a byte-stable prompt prefix (system + task) across turns, so providers that auto-cache prefixes (OpenAI, DeepSeek, Gemini, most via OpenRouter) apply the discount for free; the one provider that needs explicit cache_control markers (Anthropic) is handled by litellm when you opt in with --cache (off by default), never by branching in JAVIS. Context compression trims the non-cacheable tail. Net cost levers, all agnostic: stable prefix → auto-cache, compression, and escalating to the expensive tier only on failure.

Extending JAVIS (provider-agnostic, opt-in — see docs/extensibility.md): project context (JAVIS.md), declarative policy (.javis-policy.json), lifecycle hooks (.javis/hooks.json), reusable commands (.javis/commands/), and read-only subagents the main agent can delegate to (.javis/agents/). Autonomous sandboxing recipe in docs/autonomous-sandbox.md.

Layout

javis/
  loop.py        plan -> propose -> adjudicate -> admit
  plan.py        plan stage + plan-shape gate (gate 0)
  context.py     context window + read-set / read-content (gates 2, 2b)
  model.py       Model protocol; ScriptedModel (tests/control) + LiteLLMModel (OpenRouter)
  router.py      tiered escalation (cheap -> strong on failure / API error)
  guardrails.py  loop detection — halt a thrashing run so the router escalates
  sanitize.py    repair malformed tool-call JSON from weak models
  errors.py      API error taxonomy (rate_limit / billing / not_found / ...)
  ratelimit.py   x-ratelimit header parse + file-based cooldown guard
  budget.py      run budget
  trajectory.py  day-0 tier-labeled distillation capture
  experiment.py  the de-risk matrix runner (models x conditions x fixtures)
  distill.py     export gate-passed trajectories as tier-labeled SFT data (P5)
  failure_memory.py  mine recurring failures -> guardrail-hint candidates
  catalog.py     pick tool-capable / cheap OpenRouter models
  hooks.py       lifecycle hooks (PreTool/PostTool/Stop scripts)
  commands.py    markdown task templates (--command / /name)
  subagents.py   read-only specialized agents (delegate + PARALLEL dispatch); built-in reviewer
  repomap.py     symbol-level repo map (files + their defs/classes)
  planmode.py    human-approved plan mode (REPL /plan)
  tools/git.py   git awareness (status/diff/log) + commit-on-success
  tools/         fs (read/edit), code (grep/resolve), tests (the pytest oracle)
  gates/         resolve (1), readwrite (2/2b), parse (3), verify (6), oracle (7), policy, base
  cli.py         REPL + --headless + --sandbox + --strong-model + --cache + --command + --agent
                 + --commit + --review + --lint + --types + --map; REPL /plan
fixtures/        difficulty-graded suite L1-L6 (see fixtures/SUITE.md) + suite.json
tests/           JAVIS's own suite (the harness verifies itself)
docs/            harness-contract.md

Maturity

JAVIS has a stable core and a wider experimental surface. Both are covered by the test suite, but the core is what the correctness guarantees rest on and what every run exercises; the experimental modules are iterated less often, change faster, and are not on the correctness path.

• Stable core — the loop and gates (loop.py, gates/, tools/), the model/provider layer (model.py, router.py, errors.py, ratelimit.py), context + planning (context.py, plan.py, compress.py), guardrails.py, narrator.py, the LSP type gate (lsp.py), and the TUI/CLI.
• Experimental / research — the orchestration bake-off (orchestrate.py), the distillation pipeline (distill.py, experiment.py, failure_memory.py), the benchmark runners (swebench*.py, polyglot.py, eval_ab.py), and the plugin marketplace (marketplace.py, mcp_install.py). Useful and tested, but expect rougher edges and faster change.

Run

# JAVIS's own tests (no network, no litellm needed)
python -m pytest

# Drive a real model against a fixture (needs litellm + OPENROUTER_API_KEY)
pip install -e ".[llm]"
export OPENROUTER_API_KEY=...
javis --headless --repo fixtures/bugfix-01 --task "make the test suite pass" \
      --model openrouter/meta-llama/llama-3.1-8b-instruct --trajectory run.jsonl

# Run fully local — no cloud, no API bill (Ollama/LM Studio/vLLM). See docs/local-llm.md
javis --repo . --task "fix the failing test" --local --model ollama/qwen2.5-coder:7b

Local LLMs (incl. models with no native tool-calling) are first-class — see docs/local-llm.md.

# First-run setup wizard (pick provider/model, local or a key). See docs/setup.md
pip install -e ".[tui]"
javis --setup

# Live terminal UI — splash, welcome panel, working status, slash commands. See docs/tui.md
javis --tui --repo . --task "fix the failing test"

The agent can run shell commands behind a permission prompt, and renders multi-step plans as a live checklist — see docs/shell-and-tasks.md.

JAVIS speaks MCP — drop in the standard .mcp.json and it inherits the whole Model Context Protocol tool ecosystem (javis --mcp), gated by permission. See docs/mcp.md.

Plugins bundle commands + agents + hooks + MCP servers; JAVIS installs them from a git URL or local dir, including Claude-Code-format plugins — translated to run on any model (incl. local). A curated built-in marketplace ships in the package (javis --plugin-install code-review). See docs/plugins.md.

Measure capability — javis-eval is a lite, local, SWE-bench-style scorecard: real bug-fix fixtures, reproduce → solve → score independently with the test oracle. Headline numbers are resolved/total and false-green (claimed success the tests don't support — a trustworthy harness scores zero, and the CLI exits non-zero if any appear). See docs/eval.md.

javis-eval --strong-model openrouter/anthropic/claude-sonnet-4   # cheap base, escalate on measured failure

For a comparable number, javis-swebench points the same reproduce → solve → score loop at the SWE-bench format (real GitHub issues; checkout at base_commit, apply test_patch, score FAIL_TO_PASS/PASS_TO_PASS). See docs/swebench.md.

De-risk experiment knobs

• --no-gates — control: disable the harness (still scored by the final suite) to measure the harness's contribution.
• --plan — opt back into the self-planning stage (OFF by default; Phase 0 showed self-planning hurts completion).
• --sandbox — run on a throwaway copy of --repo, leaving the original untouched (try the agent on a fixture without mutating it).

License

Apache-2.0 © 2026 Okello Solomon Roy Jasper.