xis is a terminal tool that shows what an AI coding agent did to your code and why. It links each changed hunk to the step that made it. It also shows the instruction, the agent text and the evidence for that step.

xis flags risky behaviour with fixed rules, for example edited tests, changes out of scope and "tests pass" claims without a test run. The rules work without an LLM. An optional LLM can summarize the change and answer questions, but every statement must cite a step or a hunk.

Overview

This diagram shows how data moves from the agent to the xis commands.

flowchart LR
    agent[Agent session] --> hooks[xis hooks]
    hooks --> spool[(Spool)]
    hooks --> shadow[(Shadow repository<br/>snapshots)]
    spool --> ingest[Ingest]
    shadow --> ingest
    ingest --> db[(Database)]
    db --> review[xis review]
    db --> flags[xis flags]
    db --> why[xis why]
    db --> report[xis report]

The agent calls the xis hooks at each step. The hooks write each event to the spool and take a snapshot of the working tree after each change. When the session stops, ingest reads the spool and the transcript. Ingest removes secrets and writes the session to the database. The commands read the database.

xis captures Claude Code sessions live through hooks. It imports Codex CLI sessions from their logs, with lower fidelity. Each session shows how xis captured it: live or imported.

Install

With the install script, on Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/aaxis-em/xis/main/install.sh | sh

The script downloads the latest release for your system, checks its SHA-256 and puts xis in ~/.local/bin. To read the script before you run it, download it first:

curl -fsSLO https://raw.githubusercontent.com/aaxis-em/xis/main/install.sh
less install.sh
sh install.sh --version v0.1.0 --dir ~/bin

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/aaxis-em/xis/main/install.ps1 | iex

The script puts xis.exe in %LOCALAPPDATA%\Programs\xis and adds that folder to your user PATH. It also checks the SHA-256 of the download.

With Homebrew:

brew install aaxis-em/tap/xis

With Go 1.26 or later:

go install github.com/aaxis-em/xis/cmd/xis@latest

xis needs git 2.31 or later. It is one static binary for Linux, macOS and Windows (amd64 and arm64). On Windows, xis needs Git for Windows, which Claude Code also needs. xis keeps its config in %APPDATA%\xis and its data in %LOCALAPPDATA%\xis.

Quickstart

1. Run xis init. The command creates the config file, the database and the signing key.
2. Go to your repository.
3. Run xis hook install --agent claude-code. The command adds the hooks to .claude/settings.json.
4. Use Claude Code as usual.
5. Run xis review to walk through the change unit by unit.
6. Run xis why FILE:LINE to see the origin of one line.
7. Run xis precommit install to stop commits with high-severity flags.
8. After the commit, run xis note write. Then run xis report --md and paste the output into your pull request.

For a Codex CLI session, run xis import codex --latest in place of steps 3 and 4.

Commands

Most commands select a change with these options: SESSION, --staged, --range A..B and --pr. See docs/USAGE.md.

How xis uses an LLM

The LLM is optional. Capture, attribution, the rules, xis why, xis flags and the pre-commit hook never use it.

With an LLM, xis analyze and xis ask add intent items, better review units, hunk explanations and answers. xis checks each result:

• Every sentence must cite a valid step or hunk. xis deletes the other sentences.
• An agent claim must be an exact quote of agent text near the edit. xis marks it verified only if the record proves it.
• xis caches each response and stops at the cost limit llm.max_usd_per_change (default 0.50 USD).

The default provider is auto: Anthropic if ANTHROPIC_API_KEY is set, else none. Each OpenAI-compatible server also works, for example OpenAI, Groq, Gemini, OpenRouter or Ollama. See docs/CONFIG.md. To turn off the LLM, run xis config set llm.provider none. For one command, set XIS_LLM_PROVIDER=none.

Privacy

xis is local-first. It sends no telemetry.

• What xis stores: the redacted steps, tool calls, edits and test runs of each session, in ~/.local/share/xis/xis.db (%LOCALAPPDATA%\xis\xis.db on Windows). The snapshots are in a shadow git repository in the same directory. On Linux and macOS, all files have mode 0600.
• What xis removes: secrets (gitleaks rules, high-entropy tokens and your own patterns), before it stores data and again before each LLM call.
• What leaves your machine: nothing, unless you configure a remote LLM provider. Then xis sends only the steps and hunks that a task needs. With llm.send_code = false, it sends no file contents.

See docs/PRIVACY.md for the full data flow.

Documents

• Usage: each command with examples.
• Architecture: the design and the observed agent formats.
• Rules: each rule, its false positives and how to tune it.
• Config: every config key.
• Privacy: data, redaction, retention and the LLM data flow.
• Glossary: the project terms.
• Decisions: the decision log.
• Contributing: build, test, fixtures, adapters and rules.

License

The Apache License 2.0 applies to xis. See also NOTICE.

The name xis and the xis logo are not covered by the license.