Jarvis is a Rust agent runtime and coding workspace for building, running, and extending tool-using AI agents. It pairs a small runtime-independent harness with a web UI, terminal UI, HTTP API, MCP bridge, persistent conversations, workspace-aware tools, approval flows, and pluggable LLM providers.

English is the default README. A Chinese translation is available at README.zh-CN.md.

Jarvis is designed for coding-agent workflows, but the core harness is general-purpose:

• Run multi-turn agents over HTTP, SSE, WebSocket, or the terminal.
• Connect to OpenAI, OpenAI Responses-compatible gateways, Anthropic, Google Gemini, Codex OAuth, Ollama, Kimi, and other OpenAI-compatible providers.
• Use built-in tools for file reading/listing/editing/patching, regex code search, sandboxed shell execution, HTTP fetch, git inspection, planning, user prompts, and workspace context.
• Bind conversations to a workspace so filesystem, shell, and git operations run against the right repository.
• See the selected workspace and current git branch directly above the chat composer.
• Optionally attach a project as light context for a new session; project selection is intentionally a soft reminder rather than a blocking setup step.
• Persist conversations, projects, permissions, and workspace bindings with SQLite by default, with Postgres and MySQL behind features.
• Gate sensitive tools through approval modes and rule-based permission policies.
• Bridge tools through MCP: consume external MCP servers or expose Jarvis tools as an MCP server.
• Keep conversations within a token budget using sliding-window or summarizing memory.

The web UI is served at the server root:

open http://127.0.0.1:7001/

The app includes:

• Chat workspace with streaming assistant output and visible tool activity.
• Claude Code-style composer context chips for local runtime, workspace, git branch, optional project context, model, and permission mode.
• Sidebar conversations, quick switcher, pinned chats, account/settings menu, and connection status.
• Workspace panels for diffs, changed files, tasks, plans, preview, terminal, and change reports.
• Settings for providers, server state, workspaces, permissions, MCP, plugins, skills, appearance, and preferences.
• Work and Docs routes for project/product context and documentation surfaces.

jarvis-cli runs the same harness in-process with an interactive REPL, approval prompts, and a non-interactive pipe mode:

cargo run -q -p jarvis-cli
echo "summarize the README" | cargo run -q -p jarvis-cli -- --no-interactive

See docs/user-guide-cli.md.

Jarvis exposes OpenAI-shaped and Jarvis-native endpoints:

• POST /v1/chat/completions
• POST /v1/chat/completions/stream
• GET /v1/chat/ws
• GET /v1/conversations
• GET /v1/providers
• GET /v1/workspace
• GET /v1/workspace/diff
• GET /v1/projects
• GET /v1/projects/:id/requirements?triage_state=approved|proposed_by_*|proposed
• POST /v1/requirements/:id/{approve,reject,runs} — Triage approve / reject (with reason) / mint a fresh-session run
• GET/POST /v1/requirements/:id/todos, PATCH/DELETE /v1/requirements/:id/todos/:todo_id — structured execution/checklist items, including CI/CD commands and evidence
• GET /v1/diagnostics/{worktrees/orphans, runs/stuck, runs/failed} — doctor / forensics
• GET /v1/server/info

The WebSocket is the richest transport: it supports multi-turn state, persisted conversation resume, approval decisions, HITL responses, routing/model changes, workspace changes, and streaming AgentEvents.

v1.0 turns the kanban into a "spec-in / project-out" loop. Spec is anything the agent can read: a one-line user request, a docs/feature-x.md Jarvis fetches via fs.read, or candidates surfaced by triage.scan_candidates over TODO|FIXME|XXX|HACK comments in the workspace.

The flow:

1. Capture — talk to Jarvis in chat ("read docs/avatar-upload.md and lay out the work"). The agent calls workspace.context + fs.read, drafts a breakdown via plan.update, and after user confirmation calls project.create_or_get + requirement.create per item.
2. Triage — agent-created and scan-surfaced rows default to triage_state=proposed_by_* and land in the Triage drawer above the kanban. A human clicks 通过 / 拒绝 (the latter requires a free-text reason that lands on the activity timeline). User-typed REST creates default to triage_state=approved for back-compat.
3. Execute — open any approved Backlog card and click 新建一次运行 / Start fresh run in the detail panel. The button mints a new conversation tied to the requirement, flips status to in_progress, and jumps you into chat.
4. Auto — set an assignee_id on a card and start the binary with JARVIS_WORK_MODE=auto, or opt into unassigned work via JARVIS_WORK_ALLOW_UNASSIGNED=1. The background scheduler picks Approved rows whose depends_on are all done, drives one run per tick (configurable via JARVIS_WORK_MAX_UNITS_PER_TICK), includes the card's structured TODO/checklist items in the run prompt, and runs the per-requirement verification_plan.commands after each agent loop. Runs that need worktree isolation are scoped through git worktree add (JARVIS_WORKTREE_MODE=per_run).
5. Verify — every RequirementRun carries its verification result (stdout / stderr / exit_code per command, aggregate passed/failed/needs_review). Failed runs flip the card back to Backlog up to JARVIS_WORK_MAX_RETRIES times before writing a Blocked activity.

The full spec is in docs/proposals/work-orchestration.zh-CN.md.

The release binary embeds the web bundle at compile time, so build the frontend before building jarvis:

cd apps/jarvis-web
npm install
npm run build
cd ../..

OpenAI is the default provider:

export JARVIS_PROVIDER=openai
export OPENAI_API_KEY=sk-...
export JARVIS_MODEL=gpt-4o-mini

Other common provider settings:

# Anthropic
export JARVIS_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# Google Gemini
export JARVIS_PROVIDER=google
export GOOGLE_API_KEY=...

# Ollama-compatible local server
export JARVIS_PROVIDER=ollama
export OLLAMA_BASE_URL=http://localhost:11434/v1
export JARVIS_MODEL=llama3.2

# Codex OAuth provider
# Run `codex login` once so ~/.codex/auth.json exists.
export JARVIS_PROVIDER=codex

export JARVIS_ADDR=0.0.0.0:7001
export JARVIS_FS_ROOT=.
export JARVIS_DB_URL=sqlite://./jarvis.db

Optional tool switches:

export JARVIS_ENABLE_FS_WRITE=1
export JARVIS_ENABLE_FS_EDIT=1
export JARVIS_ENABLE_FS_PATCH=1
export JARVIS_ENABLE_SHELL_EXEC=1
export JARVIS_SHELL_TIMEOUT_MS=30000

cargo run -p jarvis -- serve --workspace /path/to/repo

Or build and run the release binary:

cargo build --release -p jarvis
target/release/jarvis serve

Then open http://127.0.0.1:7001/.

Important environment variables:

Project instruction loading mirrors Claude Code's local rules shape, but stays workspace-scoped:

• root files: AGENTS.md, JARVIS.md, CLAUDE.md, AGENT.md
• Jarvis files: .jarvis/JARVIS.md, .jarvis/AGENTS.md, .jarvis/CLAUDE.md, .jarvis/AGENT.md
• local rules: .jarvis/rules/*.md
• @include path/to/file.md is supported inside loaded files, capped at 5 levels and limited to paths under the workspace root.

Jarvis ships with a namespaced toolset:

• echo, time.now
• http.fetch
• fs.read, fs.list, fs.write, fs.edit, fs.patch
• code.grep
• shell.exec
• git.status, git.diff, git.log, git.show, git.add, git.commit, git.merge
• workspace.context, project.checks
• plan.update, ask.text, exit_plan
• todo.{list,add,update,delete} — workspace-scoped lightweight backlog
• project.{list,get,create,update,archive,restore,delete} — project CRUD
• requirement.{list,create,update,delete,start,complete,block} — kanban row CRUD; agent-created rows default to triage_state=proposed_by_agent and wait for human approval
• triage.scan_candidates — surface follow-up Requirement candidates from TODO|FIXME|XXX|HACK markers (more sources planned)
• roadmap.import — bootstrap a project + Requirements from docs/proposals/, docs/roadmap/, or ROADMAP.md
• doc.{list,search,get,upsert,create,update,delete,draft.{get,save}} — long-form document CRUD; search + upsert are tuned for natural-language doc workflows
• codex.run, claude_code.run — opt-in sub-agent runners

Mutation tools are opt-in and approval-aware. The binary composition root decides which tools are registered; harness-core only sees the ToolRegistry.

Jarvis is a Cargo workspace:

crates/
  harness-core/    Agent loop, message model, Tool/LlmProvider/Store traits
  harness-llm/     Provider implementations
  harness-mcp/     MCP client and server bridge
  harness-memory/  Sliding-window and summarizing memory
  harness-server/  Axum HTTP, SSE, WebSocket, and UI serving
  harness-store/   SQLite/Postgres/MySQL stores
  harness-tools/   Built-in tools
  harness-cloud/   Optional cloud / edge runtimes via harness-cloud
apps/
  jarvis/          Server binary and composition root
  jarvis-cli/      Terminal coding-agent UI
  jarvis-web/      React web app bundled into the server binary

The main design rule:

harness-core knows nothing about HTTP, providers, storage, MCP, or the web UI.

See ARCHITECTURE.md for the detailed layering and request lifecycle.

Run Jarvis as an MCP server exposing its local ToolRegistry over stdio:

cargo run -p jarvis -- --mcp-serve

Or consume external MCP servers at runtime:

export JARVIS_MCP_SERVERS='fs=uvx mcp-server-filesystem /tmp,git=uvx mcp-server-git'

cargo check --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
npm --prefix apps/jarvis-web run build
cargo build --release -p jarvis

When editing the web UI served by target/release/jarvis, rebuild the frontend first, then rebuild the Rust binary so the new dist/ bundle is embedded.

• README.zh-CN.md — Chinese translation.
• CHANGELOG.md — product changes.
• docs/user-guide.md — full user guide.
• docs/user-guide-web.md — web UI guide.
• docs/user-guide-cli.md — terminal UI guide.
• docs/user-guide-coding-agent.md — coding-agent walkthrough.
• ARCHITECTURE.md — system architecture.
• DB.md — persistence schema and store details.

Jarvis is usable as a local coding-agent runtime and extensible agent harness. The core loop, multiple providers, web and terminal frontends, persistent sessions, workspace-aware tools, MCP bridge, approvals, and memory are implemented. Some product surfaces are still evolving, especially long-term memory, richer project/document workflows, and provider-specific polish.