Metadata-Version: 2.4
Name: jarv
Version: 0.16.0
Summary: A multi-provider AI-powered CLI agent
Author: James W Homer
License: Elastic-2.0
Project-URL: Homepage, https://github.com/JamesWHomer/jarv
Project-URL: Repository, https://github.com/JamesWHomer/jarv
Project-URL: Issues, https://github.com/JamesWHomer/jarv/issues
Keywords: cli,agent,openai,anthropic,gemini,openrouter,llm,assistant
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: litellm>=1.0
Requires-Dist: openai>=1.0
Requires-Dist: rich>=13.0
Dynamic: license-file

# jarv

A multi-provider AI-powered CLI agent that can run shell commands, fan out work to parallel subagents, and keep track of conversation history across terminal sessions.

```bash
jarv                                    # start an interactive session
jarv whats the meaning of life?         # one-shot question
jarv commit all these files             # let it run commands to do the job
jarv refactor the auth module           # complex tasks get split across subagents
```

## Install

Requires **Python 3.10+** and an **OpenAI API key**.

```bash
pip install jarv
jarv /setup
```

The setup wizard will walk you through entering your API key and choosing a model. The key can also be set via the `OPENAI_API_KEY` environment variable or `jarv /set api_key ...`.

To upgrade:

```bash
jarv /update
```

![jarv update demo](https://github.com/user-attachments/assets/5dbbb528-6b6f-4d04-bc2d-d68652e67fc9)

## Usage

### One-shot mode

Pass a prompt as arguments. Jarv answers (running commands if needed) and exits.

```bash
jarv what process is using port 8080?
jarv find all TODO comments in src/
```

Jarv also accepts piped stdin as one-shot input. If you pass both stdin and prompt arguments, the arguments are treated as the instruction and stdin is attached as context.

```bash
git diff | jarv review this patch
cat README.md | jarv summarize this
rg TODO . | jarv group these by subsystem
```

### Heads-up mode

Run `jarv` with no arguments to enter an interactive prompt loop.

```
jarv> what files changed today?
jarv> now run the tests
jarv> /history
jarv> /new
```

- Type a prompt and press Enter.
- Slash commands start with `/` — type `/help` to list them.
- During a response, Ctrl+C stops further work, checkpoints the turn in history/context, and restores the prompt for editing. Use `/undo` to remove the turn.
- At the prompt, Ctrl+C clears existing text; press it again on an empty prompt to exit.
- You can also exit with `exit`, `quit`, or `/exit`.

![jarv interactive session](https://github.com/user-attachments/assets/d56b491b-4498-43f9-a93b-cfee7aee4791)

### Flags

Flags override config values for a single run and work in both one-shot and heads-up mode.

| Flag | Short | Description |
| --- | --- | --- |
| `--model MODEL` | `-m` | Override the model (e.g. `gpt-5.4-mini`) |
| `--effort EFFORT` | `-e` | Override reasoning effort (`low` / `medium` / `high`) |
| `--timeout SECONDS` | | Override command timeout in seconds |
| `--system PROMPT` | `-s` | Override the system prompt |
| `--new` | | Start a fresh session (ignore prior history, but still save) |
| `--incognito` | | Don't load or save session history |
| `--version` | | Print the version and exit |

```bash
jarv -m gpt-5.4-mini "summarise this repo"
jarv --effort high "refactor the auth module"
jarv --new "start fresh without prior context"
jarv --incognito "one-off task, leave no trace"
jarv --timeout 120 --system "You are a poet" "write me a haiku"
```

## How it works

Jarv wraps the OpenAI Responses API with a tool-calling agent loop. The model can call three tools:

| Tool | Purpose |
| --- | --- |
| `run_command` | Execute a shell command and return stdout, stderr, and exit code |
| `spawn` | Fan out work to parallel subagents, each with their own tool access |
| `read_artifact` | Retrieve the full output of a completed subagent |

On Windows, commands run through PowerShell. On other platforms, they run through the system shell.

### Command safety

Before executing a shell command, jarv can prompt you for confirmation. The `command_safety` config key controls this:

| Level | Behavior |
| --- | --- |
| `risky` (default) | Prompts for confirmation when a command matches dangerous patterns — recursive deletion, privilege escalation, network exfiltration, disk formatting, credential access, force pushes, and more. |
| `all` | Every command requires your explicit approval before running. |
| `none` | Commands run immediately with no confirmation prompt. |

Set the level in the settings menu (`jarv /settings`) or at any time with:

```bash
jarv /set command_safety risky    # default — confirm dangerous commands
jarv /set command_safety all      # confirm everything
jarv /set command_safety none     # no prompts
```

### Subagent orchestration

When the model calls `spawn`, Jarv runs N child agents in parallel. Each child operates independently — running commands, reasoning through subtasks — and terminates by calling `finish` with a detailed report and a short summary. The parent agent can then read any child's full output via `read_artifact`.

- **Parallel by default** — all children in a `spawn` call run concurrently in a thread pool.
- **Artifacts** — each child's output is stored as a named artifact. The parent (or siblings that declare a dependency) can fetch the full content.
- **Recursive** — children can themselves spawn further children, up to `max_subagent_depth` levels deep (default 4). Children are sterile by default; the parent must explicitly allow further spawning.
- **Transcript scope** — child-agent transcripts are discarded. Root history stores the parent `spawn`/`read_artifact` tool calls and returned outputs.
- **Scoped per query** — the artifact store resets with each new top-level prompt.

The terminal shows a live progress panel as children run, with a green checkmark or red cross as each finishes.

## Commands

![jarv slash commands](https://github.com/user-attachments/assets/ed723bce-229e-47db-82a4-c26af2c623ad)

| Command | Description |
| --- | --- |
| `/help` | Show all commands |
| `/about` | Detailed info and examples |
| `/set <key> <value>` | Set a config value |
| `/unset <key>` | Reset a config key to default |
| `/settings` | Open the interactive settings menu |
| `/config` | Show raw config values |
| `/setup` | Run the setup wizard |
| `/new` | Start a fresh session on the next prompt |
| `/archive` | Archive session history and artifacts |
| `/sessions` | Browse sessions (interactive when in a TTY) |
| `/sessions <id>` | Load a specific session by ID prefix |
| `/history` | Show recent conversation history |
| `/undo [n]` | Remove last *n* exchanges (default 1) |
| `/redo [n]` | Restore last *n* undone exchanges (default 1) |
| `/usage` | Show token usage, cost, and context breakdown for the current session |
| `/usage day` / `/usage week` / `/usage month` | Show system-wide usage for the last 24h, 7d, or 30d |
| `/usage --all [--since 24h]` | Show system-wide usage across Jarv sessions |
| `/update` | Update Jarv to the latest version |

All commands work both as `jarv /command` (one-shot) and inside heads-up mode. Read-only commands (`/help`, `/about`, `/usage`, and `/config`) use a temporary display by default in interactive terminals; change `read_only_command_display` in `/settings` to print them permanently instead.

## Sessions

Each terminal is automatically bound to its own session. Jarv identifies terminals using environment variables (`WT_SESSION`, `TERM_SESSION_ID`, `TMUX`, `STY`) with a parent-process fallback, so history persists across runs in the same terminal.

- `/new` starts a fresh session on the next prompt without archiving the current session.
- `/sessions` opens an interactive browser (arrow keys to navigate, Enter to load, `a` to archive, `d` to delete, `p` to preview, `Tab` to switch views, Ctrl+F to search).
- `/history` opens an interactive transcript where Up/Down scroll and Left/Right jump to the previous or next chat/reply.
- `/undo` and `/redo` let you step through recent exchanges.

![jarv session undo](https://github.com/user-attachments/assets/957729b0-3925-461d-a65c-25cf030ffaa6)

## Config

Settings live in `~/.jarv/config.json` (created on first run). Use `/settings` for the common controls, or edit the file directly with `/set` and `/unset`.

| Key | Default | Description |
| --- | --- | --- |
| `api_key` | `""` | OpenAI API key. Falls back to `OPENAI_API_KEY` env var if empty. |
| `model` | `"gpt-5.4-mini"` | Model name passed to the API. |
| `reasoning_effort` | `""` | Reasoning effort level. Leave empty to disable. |
| `max_history` | `40` | Number of recent stored history items included as model context. Does not delete saved history. |
| `max_stdin_chars` | `200000` | Maximum piped stdin characters attached to a one-shot prompt. |
| `max_tool_output_chars` | `20000` | Maximum tool output characters returned to the model. Longer output is returned with the middle omitted. |
| `command_timeout` | `60` | Seconds before a shell command is killed. |
| `command_safety` | `"risky"` | Command confirmation level: `all` (confirm every command), `risky` (confirm dangerous commands only), `none` (no confirmation). |
| `audit` | `true` | LLM auditor for flagged commands. |
| `auditor_auto_approve` | `true` | Let the auditor auto-approve commands it deems safe. |
| `auditor_model` | `""` | Auditor model. Empty uses the active `model`. |
| `max_subagent_depth` | `4` | Maximum nesting depth for spawned subagents. |
| `subagent_thread_pool_max_workers` | `8` | Max parallel subagents per `spawn` call. |
| `check_updates` | `true` | Background update check on startup (non-blocking, throttled to once per 24h). |
| `read_only_command_display` | `"auto"` | Display mode for `/help`, `/about`, `/usage`, and `/config`: `auto`, `print`, `inline`, or `fullscreen`. |
| `print_usage_after_agent` | `false` | Print a compact token usage line after each completed agent run. |
| `system_prompt` | `"You are Jarv..."` | System instructions sent with each request. |

## Local files

All state is stored in `~/.jarv/` (on Windows, `%USERPROFILE%\.jarv\`):

```
~/.jarv/
├── config.json                      # settings and optional API key
├── sessions.json                    # terminal → session mappings
├── sessions/
│   ├── history-<hash>.json          # conversation history
│   ├── artifacts-<hash>.json        # subagent artifacts
│   ├── usage-<hash>.json            # session token usage totals
│   └── redo-<hash>.json             # undo/redo stack
├── usage.json                       # future system-wide token usage ledger
└── archive/                         # archived sessions
```

`max_history` counts stored items, not exchanges or tokens. User messages, assistant messages, reasoning items, function calls, and function call outputs each count as one item.

System-wide usage tracking starts from the version that records `~/.jarv/usage.json`; older session totals are not backfilled into time-window reports.

## Dependencies

| Package | Role |
| --- | --- |
| [openai](https://pypi.org/project/openai/) | Responses API client |
| [httpx](https://pypi.org/project/httpx/) | Direct Anthropic Messages API transport |
| [rich](https://pypi.org/project/rich/) | Terminal styling, live rendering, markdown |
| [litellm](https://pypi.org/project/litellm/) | Token counting, model pricing, context window metadata |

## License

[Elastic License 2.0 (ELv2)](LICENSE) — free to use, modify, and redistribute. You may not offer jarv as a hosted/managed service.
