amness 0.0.0-stage → 0.1.2

package/docs/getting-started.md

@@ -0,0 +1,205 @@
+# Getting started
+
+This tutorial takes you from zero to a first useful session: you ask a question, change a file, undo the change, and make the agent prove its work.
+
+In this page you will learn:
+
+- how to install Amness and set an API key or a local model
+- how to ask a question and ask for a change
+- how to read, approve and undo a diff
+- how to make the agent prove its work and save a memory note
+
+You need Node.js 22.18 or newer, git, and a terminal. A *diff* is a view of the lines that a change adds and removes.
+
+## 1. Install Amness
+
+Amness is a package on npm. You install it with one command.
+
+1. Install it. The `-g` flag makes the `amness` command available in every folder.
+
+   ```bash
+   npm install -g amness
+   ```
+
+   This also installs the Anthropic SDK, which the Claude models use. It is an optional dependency, so Amness still installs if the SDK cannot. If you see "Claude support needs the SDK", run `npm install -g @anthropic-ai/sdk`.
+
+   You can also run Amness once without installing it: `npx amness`.
+
+2. Check that the command works.
+
+   ```bash
+   amness --version
+   ```
+
+   You see a version number, for example `0.1.0`.
+
+To update later, run `npm install -g amness@latest`.
+
+**Run the latest `main` from source.** Use this if you want a change that is not released yet, or if you want to work on Amness itself:
+
+```bash
+git clone https://github.com/amirsdream/Amness.git && cd Amness && npm install
+npm link
+```
+
+`npm link` makes the `amness` command point at your clone, so `git pull` updates it.
+
+Amness is developed on macOS and Linux. The tests also run on Windows, but Windows has **no OS sandbox** for shell commands.
+
+## 2. Set an API key or choose a local model
+
+A *provider* is the service that runs the model. Choose one way.
+
+**Option A: a cloud provider.** Set the key in your terminal. Use the key for the provider that you want.
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+For OpenAI, use `OPENAI_API_KEY=sk-...` instead. OpenAI is the default provider. If you set only an Anthropic key, run `/provider` in the chat and choose Claude.
+
+**Option B: a local model.** Install Ollama, then download a model that supports tool calling.
+
+```bash
+ollama pull qwen2.5-coder:7b
+```
+
+Start Amness, run `/provider`, and choose "Ollama (local)". You need no key. Small local models can be weak at tool calling. See [Providers and models](providers.md).
+
+You can also do nothing now. On the first start, Amness asks you to pick a provider and paste a key. It saves the key in your system's secure store (the macOS Keychain, the Linux keyring, or Windows DPAPI) and tells you which one. See [Safety](safety.md) for the details and for servers that have no keyring.
+
+## 3. Start in a project
+
+Go to a project that is under git, then start the chat.
+
+```bash
+cd ~/your-project
+amness
+```
+
+You see the full-screen chat: a header, a transcript, a sidebar and an input box.
+
+![The full-screen chat](images/chat.png)
+
+The default mode is `default`. In this mode Amness asks before it edits a file or runs a risky command.
+
+## 4. Ask a question
+
+Type a question and press `Enter`. Use `@` to attach a file.
+
+```text
+❯ what does @package.json say about how to run the tests?
+```
+
+The agent reads files and answers. Reads and searches collapse into one row, for example "Explored · 2 files read". Click the row to see the details. Nothing changes in your project, because a question only reads files.
+
+## 5. Ask for a change
+
+Now ask for a small change.
+
+```text
+❯ add a short "Contributing" section to the README
+```
+
+The agent works. The status line shows what it does, and the sidebar shows its progress.
+
+## 6. Read and approve the diff
+
+Before Amness edits a file, it stops and shows a window with the exact diff. Green lines are added. Red lines are removed.
+
+![An edit waiting for approval, with the diff](images/approval.png)
+
+1. Read the diff.
+2. Choose "Yes" to apply this one edit. Choose "No, and tell Amness what to do instead" (or press `Esc`) to refuse and give a different instruction.
+3. Choose "Yes, and accept all edits this session" only if you trust the task. Edits then apply without asking.
+
+For shell commands, Amness shows the command and asks "Run this command?". Read-only commands such as `ls` and `git status` never ask.
+
+## 7. Undo the change
+
+If you do not like the result, undo the whole turn. This reverts the files and the conversation.
+
+```text
+❯ /undo
+```
+
+You see a line such as `rewound the conversation to before turn 2 · restored 1 file(s)`. Use `/diff` to review all changes of the session before you decide. Use `/rewind` to go back to an earlier turn.
+
+Amness also tries to undo changes made by shell commands. Some commands cannot be undone. In that case Amness lists them.
+
+## 8. Make the agent prove its work
+
+By default, an agent can say "done" when the work is not done. A *verify command* is a command that must pass before the agent may finish. If it fails, Amness rejects the finish and the agent must try again.
+
+1. Choose a command that tests your project. Amness picks one for you when it finds `npm test`, `cargo test`, `go test ./...` or `pytest -q`. Type `/status` and look at the `verify` line.
+2. Set or change it in the chat.
+
+   ```text
+   ❯ /verify npm test
+   ```
+
+   You see `verify gate → npm test`.
+3. Ask for a change that touches the code.
+
+   ```text
+   ❯ the date parser fails on leap days, fix it
+   ```
+
+4. Watch the end of the turn. If the command fails, you see a note such as "finish rejected by verification" and the agent continues. If it passes, the agent finishes.
+
+For a run without a chat, the flag is `--verify`:
+
+```bash
+amness run --verify "npm test" "fix the failing test"
+```
+
+The `--verify` flag belongs to `amness run`. In the chat, use `/verify`. See [Headless and CI](headless.md).
+
+You can also set `/check <cmd>`, a fast command (for example a type check) that runs after every edit.
+
+## 9. Save a memory note
+
+A *memory note* is a short text file that the agent can read in later sessions. Start a line with `#` to save one.
+
+```text
+❯ # run tests with npm test, never with npx jest
+```
+
+You see "remembered" and the note name. Type `/memory` to list your notes. Notes live in `.amness/memory` in your project.
+
+## 10. Go further
+
+Two more screens help you understand what the agent does. Subagents are helpers that the agent starts for large searches. You see one card while it runs and a summary when it ends.
+
+![A subagent card while it runs](images/subagent-running.png)
+
+![The same card when it has finished, with its report and its cost](images/subagent-done.png)
+
+Type `/loop` to see every model turn, its tools and timings.
+
+![The /loop view](images/loop.png)
+
+Type `/tokens` to see how full the context is and what the session costs. Costs are estimates.
+
+When you finish, type `/exit` or press `Ctrl+C` twice. Your conversation is saved. Next time, run `amness -c` to continue it.
+
+## If something goes wrong
+
+| What you see | What it means | What to do |
+|---|---|---|
+| The first start asks for a provider and key, or a message says "no API key" | Amness has no key for the provider. In `amness run`, the message is `no API key for <provider>. Set ANTHROPIC_API_KEY or OPENAI_API_KEY or run amness settings`. | Set the key (step 2), or run `/provider`. For a local model, choose Ollama. |
+| "check your key with /provider" | The provider rejected the key (401 or 403). | Run `/provider` and enter the key again. |
+| "rate limited by the provider: waiting 12s, then retrying" | The provider has limits on requests and tokens each minute. Amness waits and retries for you. | Wait. If it happens often, set a lower `"maxConcurrent"` in `~/.amness/config.json`. Quota and billing errors are not retried. |
+| "token budget exhausted" or a line starting with `stopped:` and a budget message | The turn used its token cap (300,000 by default). Amness asks the model to wrap up at 50, 75 and 90 percent and writes a final report. | Read the report. Send a message to continue, ask a smaller question, or raise the cap with `/budget 500k`. |
+| "denied: ..." | A permission rule or the safety floor refused the command. In `amness run`, risky commands are denied unless you pass `--yes`. | Read the reason. Use `/policy` to see why. Allow the command with `/permissions allow sh(npm test*)`, or in `amness run` pass `--yes` in a safe place. |
+| "finish rejected by verification" | Your verify command failed. | This is the gate working. Let the agent fix the problem, or check that the command is right with `/verify`. |
+| "interrupted. Your progress is kept" | You pressed `Esc` or `Ctrl+C`. | Send a message to continue. |
+
+## Next steps
+
+- [Using the chat](usage.md): all keys, modes and slash commands.
+- [Providers and models](providers.md): OpenAI, Claude and local models.
+- [Headless and CI](headless.md): run Amness in scripts.
+- [Safety and privacy](safety.md): what the permission system protects.
+- [Budgets and subagents](budgets.md): why runs stop and how to control cost.
+- [Features in depth](features.md): worktrees, pull requests, hooks, skills and more.

package/docs/headless.md

@@ -0,0 +1,188 @@
+# Headless and CI
+
+*Headless* means that Amness runs one task without a chat window, so you can use it in scripts and in CI (continuous integration, the system that tests your code on each change).
+
+In this page you will learn:
+
+- how to run one task with `amness run`
+- how to make the agent prove its work with `--verify`
+- how to read the JSON output and the exit codes
+- how to run several attempts or several parts at once
+
+## Run one task
+
+**What it is.** `amness run` runs a single task and then exits. It needs no terminal. `amness -p "task"` and `amness --print "task"` do the same.
+
+**Why you would use it.** You can call Amness from a script, a scheduled job or a CI step.
+
+**How to use it.**
+
+1. Set a key for your provider (see [Providers and models](providers.md)).
+
+   ```bash
+   export ANTHROPIC_API_KEY=sk-ant-...
+   ```
+
+2. Run a task with a check command. The agent cannot finish until the command exits with code 0.
+
+   ```bash
+   amness run --verify "npm test" --json "fix the failing test"
+   ```
+
+3. Read the result. Without `--json`, the final text of the agent goes to stdout and the progress goes to stderr.
+
+**Example.** With `--json`, each event is one JSON line, and the last line is the result:
+
+```json
+{"kind":"result","finished":true,"text":"...","steps":8,"tokens":15200}
+```
+
+The values are an example. The field `stopped` is missing when the run ends normally. When the run stops early, it is `budget`, `maxSteps`, `aborted`, `stuck` or `blocked`. If a model call fails, the last line is `{"kind":"error","message":"..."}`.
+
+**Exit codes.**
+
+| Code | Meaning |
+|---|---|
+| `0` | The agent finished. |
+| `1` | The agent did not finish, or an error happened. |
+| `2` | Usage or configuration error (for example no task, or no API key). |
+
+**Limits and common problems.**
+
+- If you give no task and no `--bundle`, Amness prints the usage text and exits with 2.
+- If there is no API key, Amness says so and exits with 2. Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
+- Without `--verify`, nothing proves the work. The agent only says it is done.
+
+## Flags
+
+| Flag | What it does |
+|---|---|
+| `--cwd <dir>` | The workspace. The default is `.`. |
+| `--verify <cmd>` | A command that must exit 0 before the agent may finish. |
+| `--check <cmd>` | A fast command that runs after every edit. The agent sees failures at once. |
+| `--trust-project` | Runs this project's `.amness/hooks.json` and plugins, and honours its allow rules. They run code, so they are off by default in headless runs. `--trust-hooks` is an older name for the same flag. |
+| `--sandbox <mode>` | Runs shell commands under an OS sandbox: `workspace` (write only in the project and temp folders) or `strict` (also no network). The same limits apply as in the chat: **Windows has no OS sandbox**. |
+| `--provider`, `--model`, `--base-url`, `--effort`, `--api` | Model selection. `--effort` accepts `none`, `low`, `medium`, `high`, `xhigh` or `max`. `--api` accepts `auto`, `responses` or `chat`. |
+| `--yes` | Approves risky commands automatically. The default is to deny them. |
+| `--json` | Prints one JSON event per line on stdout, then a final `{"kind":"result"}` line. |
+| `--bundle <file>` | Continues from a portable session bundle. You can omit the task. |
+| `--export <file>` | Writes a portable session bundle when the run ends. |
+| `--live [port]` | Serves the browser live view. The address goes to stderr. |
+| `--review` | An independent reviewer writes acceptance criteria and checks the work. It costs extra model calls. |
+| `--approval-reviewer` | A second model approves clearly safe risky calls. Without `--yes`, calls that it does not clear are still denied. |
+| `--image <file>` | Shows the model a picture. You can repeat it, up to 4 times. Allowed: png, jpg, gif, webp, up to 5 MB each. It needs a vision model. |
+| `--best-of <n>` | Tries the task up to n times in separate git worktrees. See below. |
+| `--parts <file.json>` | Runs independent parts at the same time. See below. |
+| `--trace <file>` | Writes a JSONL trace of every loop event. Set `AMNESS_OTLP=<collector url>` to export with OpenTelemetry. |
+| `--max-tokens <n>` | A hard token cap. The default is 300,000 (or the value in your config). |
+| `--no-memory` | Turns memory off. |
+
+`amness eval` has its own flags. See [Evaluating the harness](evaluation.md).
+
+## Make a run safe in CI
+
+**Why you would use it.** In CI nobody can answer a question, so Amness must decide alone.
+
+**How it behaves.**
+
+1. Risky commands are **denied** by default. The agent gets the message "non-interactive run: risky commands are denied unless --yes is passed".
+2. Project hooks, plugins and allow rules are **ignored** unless you pass `--trust-project`. Amness prints a note when it ignores them.
+3. Pass `--yes` only in a container or a throwaway checkout with your work committed. The shell is not sandboxed unless you add `--sandbox workspace` or `--sandbox strict`.
+
+**Example.**
+
+```bash
+amness run --sandbox workspace --verify "npm test" "make the date parser handle leap days"
+```
+
+**Limits and common problems.**
+
+- `--yes` approves risky commands. The safety floor still applies (for example, no force-push to main). See [Safety and privacy](safety.md).
+- The run ends with exit code 1 when the token cap is reached. The last text then starts with `stopped:`. Raise `--max-tokens` or give a smaller task. See [Budgets and subagents](budgets.md).
+
+## Try the task several times with `--best-of`
+
+**What it is.** Amness tries the task up to n times, each in its own git worktree (a separate copy of your repository). It stops at the first attempt that passes `--verify`, and it applies that result.
+
+**Why you would use it.** One attempt can fail by chance, and a second attempt may pass.
+
+**How to use it.**
+
+```bash
+amness run --best-of 3 --verify "npm test" "make the flaky test deterministic"
+```
+
+You see one line on stderr for each attempt, for example `attempt 1: failed verify (41200 tokens)`. At the end Amness says which attempt won, or that no attempt passed.
+
+**Limits and common problems.**
+
+- `--verify` is required, and so is a git repository with at least one commit. Otherwise Amness exits with 2.
+- Each attempt gets the token cap divided by n.
+- Exit code is 0 only if an attempt won and Amness applied it.
+- It is implemented and unit-tested. It is **not shown yet to help on real work**.
+
+## Run independent parts with `--parts`
+
+**What it is.** You give a JSON file with a list of tasks. Amness runs them at the same time in worktrees and merges them one at a time. Each merge must pass `--verify`.
+
+**How to use it.**
+
+1. Write the file.
+
+   ```json
+   [
+     {"name": "docs", "task": "update the README install section"},
+     {"name": "tests", "task": "add a test for the date parser"}
+   ]
+   ```
+
+2. Run it.
+
+   ```bash
+   amness run --parts parts.json --verify "npm test"
+   ```
+
+**Limits and common problems.**
+
+- Amness reports conflicts and does not apply them.
+- The exit code is 0 only when every part is `merged`.
+- The same requirements as `--best-of` apply (`--verify`, a git repository). It is **not shown yet to help on real work**.
+
+## Continue a run elsewhere
+
+**How to use it.**
+
+1. Write a bundle at the end of a run.
+
+   ```bash
+   amness run --export bundle.json "start the refactor"
+   ```
+
+2. Continue on any machine or model.
+
+   ```bash
+   amness run --bundle bundle.json "continue"
+   ```
+
+## Docker and GitHub Actions
+
+- A `Dockerfile` is included: `docker build -t amness .`, then `docker run -it --rm -v "$PWD":/work -e ANTHROPIC_API_KEY amness`. CI builds the image and runs `--version` and a self-test in it (see [Development](development.md)).
+- **Keys in Docker.** Inside a container Amness never saves a key to disk. Pass it in one of two ways:
+  - an environment variable: `-e ANTHROPIC_API_KEY` (with no value, Docker copies it from your shell, so it is not typed on the command line);
+  - a Docker secret, which is mounted as a file: `-e ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic`. `OPENAI_API_KEY_FILE` and `TAVILY_API_KEY_FILE` work the same way.
+
+  The image sets `AMNESS_KEYSTORE=none`. Amness also detects `/.dockerenv` and Kubernetes on its own. If you type a key into the chat in a container, it is used for that session only.
+- The repository has a GitHub Action in `action.yml`. Its inputs are `task`, `verify`, `provider`, `model`, `max-tokens` and `comment`. See [Features: Scheduled runs and the GitHub Action](features.md#scheduled-runs-and-the-github-action).
+
+## Related pages
+
+- [Using the chat](usage.md)
+- [Providers and models](providers.md)
+- [Safety and privacy](safety.md)
+- [Evaluating the harness](evaluation.md)
+
+## Next steps
+
+- [Getting started](getting-started.md)
+- [Budgets and subagents](budgets.md)
+- [Features in depth](features.md)

package/docs/index.md

@@ -0,0 +1,25 @@
+# Amness documentation
+
+These pages explain how to install, use, extend and trust Amness. Start with "Getting started" if you are new.
+
+| Page | What is in it |
+|---|---|
+| [Getting started](getting-started.md) | Install Amness, set a key, and finish your first task |
+| [Using the chat](usage.md) | The interface, keys, permission modes, slash commands, themes and copying |
+| [Features in depth](features.md) | Permissions, sandbox, hooks, skills, subagents, routing, memory, tracing, replay and undo |
+| [Plugins](plugins.md) | Change the agent with code: loop rules, guardrails, tools, graders and variants you can evaluate |
+| [Build your own harness](build-your-own-harness.md) | A tutorial: from one small rule to a custom harness that you measure |
+| [Cookbook](cookbook.md) | Short recipes for common jobs |
+| [Evaluating the harness](evaluation.md) | `amness eval`: measure a change with statistics, ablations, benchmarks and an injection suite |
+| [Compare coding agents](bench.md) | `amness bench`: run Amness, Claude Code, Codex or any tool on the same tasks, with a Windows setup |
+| [Budgets and subagents](budgets.md) | Why runs ran out of budget, what vendors and papers say, and what Amness does about it |
+| [The agent loop](agent-loop.md) | Staged compaction, guards, the claims ledger, cache behavior and sources |
+| [Architecture](architecture.md) | The layers, the files, and how the full-screen interface draws |
+| [Providers and models](providers.md) | OpenAI, Claude, and local models (Ollama, LM Studio, vLLM), and how requests are made |
+| [Headless and CI](headless.md) | `amness run`, flags, JSON events, exit codes and Docker |
+| [Use it as a library](library.md) | Use `createCodeAgent`, `createHarness`, tools and models in your own TypeScript code |
+| [Safety and privacy](safety.md) | What leaves your machine, what protects you, and what does not |
+| [Why: what Amness checks](why.md) | The mechanical agent failures that Amness guards against, with examples |
+| [Development and limitations](development.md) | Run the tests, find your way around the code, add a feature, and see the known limits |
+| [How we write the documentation](writing-guide.md) | The rules for writing these pages in plain English (CEFR level B1) |
+| [Roadmap](../ROADMAP.md) | What is done and what is next |