chivgent 1.0.1 → 1.1.0

package/README.md

@@ -1,170 +1,148 @@
 <p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/chivgent-banner-dark.svg">
-    <img src="docs/assets/chivgent-banner-light.svg" alt="chivgent: terminal coding agent. Read-only by default, Docker shell, OpenAI-compatible." width="100%">
-  </picture>
+  <img src="docs/assets/chivgent-leaf-mark.png" width="88" alt="">
 </p>
 
+<div align="center">
+
 # chivgent
 
-[English](README.md) | [简体中文](README.zh-CN.md)
+### A coding agent in your terminal.
+
+The same category as Claude Code and Codex. You bring the model.
 
-[![npm](https://img.shields.io/npm/v/chivgent)](https://www.npmjs.com/package/chivgent)
-[![CI](https://github.com/chivopic/chivgent/actions/workflows/ci.yml/badge.svg)](https://github.com/chivopic/chivgent/actions/workflows/ci.yml)
-![Node.js >=22](https://img.shields.io/badge/Node.js-%3E%3D22-339933?logo=nodedotjs&logoColor=white)
+[![npm](https://img.shields.io/npm/v/chivgent?color=111111)](https://www.npmjs.com/package/chivgent)
+[![CI](https://img.shields.io/github/actions/workflow/status/chivopic/chivgent/ci.yml?label=CI&color=111111)](https://github.com/chivopic/chivgent/actions/workflows/ci.yml)
+![Node.js >=22](https://img.shields.io/badge/Node.js-%3E%3D22-111111)
+[![License](https://img.shields.io/badge/license-MIT-111111)](LICENSE)
 
-chivgent is a terminal coding agent you can read end to end. It asks an LLM
-(OpenAI, DeepSeek, or any OpenAI-compatible endpoint) about the project in your
-current directory, using read-only file tools by default. Writes and shell
-commands are separate opt-in flags, and shell commands run in an offline Docker
-container with per-command approval.
+[Architecture](docs/architecture.md) · [Shell](docs/shell-sandbox.md) · [Sign in](docs/subscription-oauth.md) · **English** · [简体中文](README.zh-CN.md)
 
-It is small on purpose: a TypeScript CLI with four runtime dependencies, where
-the agent loop, Provider adapters, context compaction, and tool sandboxing are
-each a few hundred lines you can study.
+</div>
 
-**Use it if** you want a coding agent whose every mechanism you can inspect and
-change, or a reference implementation for building your own.
-**Look elsewhere if** you want the most capable agent for daily work, a hosted
-product, a fine-grained permission system, or native Windows shell support.
+chivgent is a local agent for the directory you have open. The category is the one [Claude Code](https://code.claude.com) and [Codex](https://github.com/openai/codex) occupy: read the project, change it, run it, and come back to the session. The model is yours. An API key, or a ChatGPT or xAI subscription.
 
-## Quick start
+The default that category expects is auto mode. Ordinary reads, workspace edits, and sandboxed commands proceed. The agent stops when an action leaves the workspace, or when a command needs the host. Here that policy is `workspace`. It is not a second model reviewing each action, and it is not a bypass. This build does not start there. A session still opens read-only. Pass `--permission-mode workspace`, or the older flags.
 
-You need Node.js 22 or newer and an API key for one Provider.
+## Getting started
+
+You need Node.js 22 or newer.
 
 ```bash
 npm install -g chivgent
-chivgent --version
 ```
 
-This prints the installed version, such as `1.0.0`. Then, from the project you want to ask
-about:
+Already installed? `chivgent update --check`, then `chivgent update`.
+
+Start it in the project.
 
 ```bash
-export OPENAI_API_KEY="your-api-key"
-chivgent "What does this project do, and where is its entry point?"
+cd /path/to/project
+chivgent
 ```
 
-The answer streams to stdout. Tool activity (`list_files`, `search_text`,
-`read_file`) is shown on stderr. Nothing in the project is changed.
+No key is required to open the session. Type `/provider` and enter one when asked, or export one first. Keys are saved for your user only, in `~/.chivgent/auth.json`.
 
-Prefer DeepSeek or another Provider? Swap the key and add `--provider`:
+```bash
+export OPENAI_API_KEY="your-api-key"
+```
+
+In a session, `/login oauth openai` or `/login oauth xai` signs in with a subscription. On a normal start, a key still takes precedence. [Subscription sign-in](docs/subscription-oauth.md).
 
 ```bash
-export DEEPSEEK_API_KEY="your-api-key"
-chivgent --provider deepseek "Explain the architecture in src/"
+chivgent "Where is the entry point?"                     # reads, then answers
+chivgent --permission-mode workspace "Run tests and fix them"
+chivgent --permission-mode ask-first "Review this project"
+chivgent --allow-writes "Rename sayHi to greet"         # older flag, not with a mode
+chivgent --allow-shell "Run the tests"                  # asks, then Seatbelt or Docker
+chivgent --provider deepseek "Explain src/"
+chivgent --tui                                           # live region, multi-line editor
+chivgent --continue                                      # last session in this directory
 ```
 
-Run `chivgent` with no question for an interactive session. If no key is set,
-the session still starts: type `/provider`, pick one, and enter its key when
-asked. Keys are saved owner-only in `~/.chivgent/auth.json`.
+## Modes
+
+| Mode | What proceeds | This build |
+| --- | --- | --- |
+| `workspace` | Workspace edits and sandboxed commands. Network stays off. A command that needs the host asks once, for that command only. | The auto-style default we want. Opt in with `--permission-mode workspace`. |
+| `ask-first` | Reads. Each file change and each command asks. No answer means no action. | `--permission-mode ask-first` |
+| `unrestricted` | Shell commands run with broad host file access and network, inside the OS sandbox. File tools stay in the workspace. | Explicit opt-in. |
+| none | Reads. Writes and shell wait for a flag. Each command asks. | What `chivgent` does now. |
+
+`--permission-mode` replaces the flags for this process. It cannot be combined with `--allow-writes`, `--allow-shell`, `--approve-all-shell`, or `--shell-network`, and it cannot be used with `--serve` or `--connect`. `/permissions` inspects or changes the mode, only in a session that started with one. The choice is not saved in the transcript. Resuming a session uses the mode you selected at startup, not a broader one from last time.
+
+`/plan` is separate. It keeps the agent on read tools and a plan. Writes, shell, and extension tools stay blocked even if the model asks for them.
 
-**Try it without a key or network:** from a source checkout, `npm run demo:tui`
-runs the TUI against a stub Provider and does not touch the workspace.
+## How it fits together
 
-## What it can do, and what it needs from you
+You type in the terminal. chivgent calls the provider you picked. File tools stay inside the current directory. The shell runs in a sandbox and does not receive your provider keys. On the default start, the shell is off until you turn it on.
 
-| Capability | Flag | What it can touch |
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/fit-dark.svg">
+  <img src="docs/assets/fit-light.svg" width="920" alt="The default start: you, chivgent, the provider you picked, this directory, and a sandbox only if shell is on.">
+</picture>
+
+## What it can touch
+
+This is the build, not the auto-style default above.
+
+| | How | What it can reach |
 | --- | --- | --- |
-| Discover, search, and read files | default | The current directory only. `.gitignore`d, generated, and credential paths (such as `.env`, `id_rsa`) are skipped. |
-| Create and edit files (`write_file`, `edit_file`, `apply_patch`) | `--allow-writes` | Files inside the workspace. Edits are exact-match and atomic. |
-| Run shell commands (`bash`) | `--allow-shell` | A fresh `node:22-alpine` Docker container with no network, the workspace mounted at `/workspace`, and no API keys. Each command needs a `y` to run. Docker is required; there is no fallback to the host. |
-| Load project extensions | trust prompt on first run | Anything you can: extensions are in-process JavaScript. |
+| Read the project | on | This directory. Ignored, generated, and credential paths are skipped. |
+| Change files | `--allow-writes` | Files inside the workspace. An edit has to match exactly, and it is written atomically. |
+| Run a command | `--allow-shell` | Seatbelt on macOS, Docker elsewhere. Network is off. Each command requires confirmation. |
+| Pick a policy | `--permission-mode` | `ask-first`, `workspace`, or `unrestricted`. Replaces the flags for this process. |
 
-Costs: chivgent calls the Provider you choose with your key, so you pay that
-Provider's normal token prices. It reports token counts per turn and per
-session (`/session`) but never converts them to money.
+You pay the provider you picked, at their prices. chivgent shows token counts; it does not convert them into costs.
 
 ## Providers
 
-| Provider | `--provider` | API key variable | Default model |
+| Provider | `--provider` | Key | Model |
 | --- | --- | --- | --- |
-| OpenAI (Responses API) | `openai` (default) | `OPENAI_API_KEY` | `gpt-5.6` |
+| OpenAI, Responses API | `openai` (default) | `OPENAI_API_KEY` | `gpt-5.6` |
 | DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek-v4-flash` |
-| Any OpenAI-compatible endpoint | `openai-compatible` | `OPENAI_API_KEY` + `OPENAI_BASE_URL` | set `OPENAI_MODEL` |
+| Any compatible endpoint | `openai-compatible` | `OPENAI_API_KEY` and `OPENAI_BASE_URL` | set `OPENAI_MODEL` |
 | OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | set `OPENROUTER_MODEL` |
 | Groq | `groq` | `GROQ_API_KEY` | set `GROQ_MODEL` |
 | xAI | `xai` | `XAI_API_KEY` | set `XAI_MODEL` |
 | Moonshot | `moonshot` | `MOONSHOT_API_KEY` | set `MOONSHOT_MODEL` |
 
-`--model` overrides the model variable. Keys resolve in this order: `--api-key`,
-then the environment variable, then `~/.chivgent/auth.json` (literal keys only;
-no `$VAR` expansion or command substitution). A custom `OPENAI_BASE_URL`
-receives your key and prompts, so point it only at endpoints you trust.
+`--model` overrides the model variable. Keys resolve in this order: `--api-key`, then the environment variable, then `~/.chivgent/auth.json`. A custom base URL receives your key and your prompts. Point it only at an endpoint you trust.
 
-Compatible endpoints must implement `POST /chat/completions` with function tool
-calling. Changing only the base URL does not guarantee full compatibility; see
-[architecture](docs/architecture.md#openai-compatible-providers).
+A compatible endpoint must implement `POST /chat/completions` with tool calling. Changing the base URL does not guarantee full compatibility. [Architecture](docs/architecture.md#openai-compatible-providers).
 
-## Everyday use
+## A session you can come back to
 
-```bash
-chivgent                                   # interactive session
-chivgent --continue                        # resume the latest session here
-chivgent --allow-writes "Rename sayHi to greet everywhere"
-chivgent --allow-shell "Run the tests and explain the failure"
-chivgent --json "List the CLI flags" > run.jsonl   # machine-readable events
-```
+Run `chivgent` with no question for an interactive session. It is saved under `~/.chivgent/sessions`. `--continue` resumes the latest one in this directory. `/resume` lists the others, and only opens sessions from here.
+
+`/compact` summarizes older turns and keeps the full transcript to resume later. `/status` shows the model, the permissions, and token usage. `/help` lists the rest.
+
+`--tui` adds a live status region and a multi-line editor. [TUI](docs/tui-v5.md). A long session stays within the context window by summarizing older turns and keeping the list of files read and changed. [Context](docs/architecture.md#context-management).
 
-- **Interactive sessions** keep history across prompts and are saved as JSON
-  lines under `~/.chivgent/sessions` (`--no-session` to skip). `/help` lists
-  slash commands such as `/provider`, `/model`, `/login`, `/session`, `/diff`,
-  and `/exit`. Ctrl+C stops a running answer; at an idle prompt it exits.
-- **`--tui`** adds a live status region and a multi-line editor with history,
-  an inline `/` command menu, and `/gitdiff` review. See the
-  [TUI guide](docs/tui-v5.md).
-- **Long sessions** stay inside the context window: older turns are summarised,
-  while the list of files read and changed is kept from the tool calls
-  themselves. See [architecture](docs/architecture.md#context-management).
-- **Exit codes:** `0` answered, `1` configuration or Provider failure, `2` turn
-  limit reached, `130` interrupted.
-- **Updating:** `chivgent update --check`, then `chivgent update`. See
-  [updating](docs/updating.md).
-
-`chivgent --help` prints every flag.
-
-## Security model
-
-chivgent states its boundaries rather than pretending to enforce fine-grained
-ones. Capabilities are coarse, session-level switches.
-
-- File tools reject paths outside the workspace, including `..` traversal and
-  symlink escapes, and deny common credential and private-key paths. Tool output
-  is capped at 64 KiB.
-- `--allow-shell` runs each command in a new offline container (dropped
-  capabilities, read-only root, non-root user, resource limits) and asks before
-  each one. Headless and served sessions deny commands unless you also pass
-  `--approve-all-shell`. Inside the container, commands can still change or
-  delete anything in the mounted project, and Docker is not proof against
-  kernel or VM escapes. Details: [shell sandbox](docs/shell-sandbox.md).
-- Writes and trusted extensions are **not** inside the container. Trusting a
-  project's extensions means letting its authors run code as you, so chivgent
-  asks once per directory and never loads them when there is no terminal to ask.
-- `auth.json`, session logs, and `trust.json` are written owner-only but in
-  plain text. Session logs contain prompts, answers, and file excerpts.
-- `--serve` exposes a session on a Unix socket in an owner-only directory.
-  Anyone who can open the socket gets every capability the server started with.
-  There is no TCP listener; use SSH forwarding for another machine.
-
-Work on committed code, and use a disposable copy for repositories you don't
-trust.
-
-## Going deeper
-
-- [Architecture](docs/architecture.md): agent loop, runtime events, context
-  compaction, Provider adapters, the TUI live region, and the source layout.
-- [Evals and token usage](docs/evals.md): ten deterministic task suites that
-  measure pass rates over repeated attempts, separate from the free, offline
-  unit tests.
-- [Extensions and remote sessions](docs/extensions-and-remote.md): adding
-  tools and slash commands, project trust, and attaching several terminals to
-  one session.
-- [Patch format](docs/apply-patch.md), [scoped `AGENTS.md`](docs/scoped-agents-md.md),
-  [parallel read tools](docs/parallel-read-tools.md),
-  [plan tracking](docs/agent-plan-progress.md).
-- Design notes for each build stage, from
-  [stage 1](docs/stage-1-minimal-agent.md) to [stage 14](docs/stage-14-tui.md),
-  and the [release process](docs/releasing.md).
+## Boundaries
+
+- Paths outside the workspace are rejected, including `..` and symlink escapes. Common credential paths are denied. Tool output is capped.
+- With no mode selected, `--allow-shell` asks before each command. A headless or served session denies commands unless you also pass `--approve-all-shell`. If the sandbox cannot start, the command does not run unsandboxed.
+- `workspace` runs workspace edits and sandboxed commands on its own, and asks once when a command wants host file and network access. `unrestricted` is the explicit opt-in for broad host access and network. Neither is saved with the session. [Shell safety](docs/shell-sandbox.md).
+- The macOS sandbox can still read files your user can read. It restricts writes and network access. It is not confidentiality isolation.
+- There is no per-command allowlist, and no native Windows shell. `workspace` is not the start mode of this build.
+- Extensions are JavaScript in the chivgent process. Trusting a project means letting its authors run code as you. chivgent prompts once per directory, and does not load extensions when there is no terminal to prompt.
+- Keys, subscription credentials, and session logs are owner-only and stored in plain text. Logs contain prompts, answers, and file excerpts.
+- `--serve` puts the session on a Unix socket in an owner-only directory. Anyone who can open the socket gets every capability the server started with. There is no TCP listener.
+
+Work on committed code. Use a copy for a repository you do not trust.
+
+This repository also has an Electron app, aimed at a local workbench on the same agent. The current build is a prototype. It is not how you use chivgent today. [Desktop plan](docs/desktop-architecture.md).
+
+## Documentation
+
+| | |
+| --- | --- |
+| [Architecture](docs/architecture.md) | The loop, providers, context, and where the source lives |
+| [Shell safety](docs/shell-sandbox.md) | Seatbelt, Docker, and what a command can still read |
+| [Subscription sign-in](docs/subscription-oauth.md) | ChatGPT and xAI: what is stored, and what a key still does |
+| [TUI](docs/tui-v5.md) | The live region, the editor, and diff review |
+| [Evals](docs/evals.md) | Whether the agent finishes the task, separate from the unit tests |
+| [Extensions and remote sessions](docs/extensions-and-remote.md) | Tools you add, and attaching another terminal |
 
 ## Development
 
@@ -172,17 +150,10 @@ trust.
 git clone https://github.com/chivopic/chivgent.git
 cd chivgent
 npm install
-npm run check
 npm test
-npm run build
 ```
 
-Tests use scripted LLM clients and never spend API credits.
-`npm run release:check` runs the full gate, including an `npm pack` dry run.
-To try the checkout as a global command: `npm install -g .`
-
-Issues and focused pull requests are welcome. Keep Provider-specific types in
-`src/providers/` so the agent runtime stays independent of vendor SDKs.
+Tests use scripted model clients and do not spend API credits. Issues and focused pull requests are welcome. Keep provider-specific types in `src/providers/`, so the agent does not depend on a vendor SDK.
 
 ## License