Auwai
A deterministic coverage layer for reading a codebase through a small model context.
Status: Auwai 1.0.0. Python 3.10 or newer. MIT.
How it works
Auwai indexes a repository into stable chunks, plans reads that fit the model window, records what was read, and keeps the map, findings, and coverage across fresh sessions.
The repository includes a static documentation site builder and a Cloudflare Pages workflow. The site renders these pages with inline diagrams: wheel zooms a diagram, drag pans, and Ctrl + wheel scrolls the page.
The site is published at https://auwai.pages.dev/. The workflow in
.github/workflows/cloudflare-pages.yml builds _site/ and deploys it with
Wrangler. The first deploy needs a Cloudflare Pages project named auwai and
the repository secrets CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID.
Without those secrets the build still runs and the deploy step is skipped.
Build the site locally:
python -m pip install '.[docs]'
make docs-site
python -m http.server -d _site 8000
Then open http://127.0.0.1:8000/.
Install
Install the release wheel:
python -m pip install auwai_kernel-1.0.0-py3-none-any.whl
auwai --version
auwai doctor
Optional database and queue clients stay out of the core install:
python -m pip install 'auwai-kernel[postgres]'
python -m pip install 'auwai-kernel[mysql]'
python -m pip install 'auwai-kernel[queues]'
From a checkout:
git clone https://github.com/SyntaxErr0r42/auwai.git
cd auwai
mkdir -p ~/.config/auwai
cp config.example.toml ~/.config/auwai/config.toml
./auwai index --repo /path/to/repo
./auwai survey --repo /path/to/repo
./auwai fullread plan --repo /path/to/repo
./auwai fullread next --repo /path/to/repo
The first pass reports the first-party scope, the partition tree, and the segments needed to read the whole repository. The full-read commands walk those segments and keep the coverage ledger.
See install for wheel, checkout, extras, and verification details.
What it does
Auwai indexes a repository into stable chunks and keeps the map, findings, coverage, and turn state in SQLite. The core has no runtime dependencies beyond Python. codebase memory is an optional companion, not a requirement. A skill-aware gateway is optional; Auwai remains an ordinary skill bundle.
It separates three budgets:
- the index budget, which is CPU and disk only;
- the read budget, which is large during a first pass and small during maintenance;
- the carry budget, which keeps the map and findings through a context reset.
A full read is a sequence of fresh model sessions. Each session gets a database-generated brief, reads one segment, records findings, and stops. The model does not hold the repository; the database does.
Knowledge layer
The default install is one SQLite ledger per repository. On top of it, Auwai builds a compact facts layer and can sync it to a team knowledge service.
auwai facts build --repo .
auwai facts search auth --repo .
auwai facts stats --repo .
# Optional team mode
auwai serve --database sqlite:///var/lib/auwai/knowledge.sqlite
auwai sync --repo .
auwai sync --repo . --pull
auwai fullread plan --share --jobs
auwai fullread claim --remote --worker agent-1
The service requires bearer auth, supports scoped tokens, and runs on SQLite, PostgreSQL, MySQL, or MariaDB. The job queue defaults to the database and can switch to Redis Streams, RabbitMQ, or Kafka.
Schema upgrades are explicit:
auwai serve --database "$AUWAI_DATABASE" --check
auwai serve --database "$AUWAI_DATABASE" --migrate
See knowledge service and security.
Harness plugins
Auwai ships one generated plugin architecture for Claude Code, Codex, Hermes, and OpenCode. All four expose the same skill, five commands, reader agent, 17 MCP tools, knowledge-service default, session nudge, raw-read guard, and stop sync.
make plugins
python3 scripts/install_plugin.py --harness opencode --scope project
python3 scripts/install_plugin.py --harness hermes --scope user
python3 scripts/install_plugin.py --harness claude --scope user
python3 scripts/install_plugin.py --harness codex --scope user
The capability matrix and install details are in Harness plugins.
Documentation
Start with docs/README.md.
| Section | What it covers |
|---|---|
| Overview | What Auwai is, the mental model, and the glossary |
| Architecture | Scope, partitions, segments, ledger, and retrieval |
| Workflows | Full read, delta, query, workspace, and recovery |
| Reference | CLI, configuration, schema, file layout, and chunk ids |
| Operations | Install, security, watch, audit, performance, troubleshooting |
| Development | Contributing, testing, providers, release, and decisions |
| Roadmap | Committed stages and release evidence |
| Benchmarks | Local replication, method, results, and calibration |
Benchmarks
Benchmarks are local-only. There is no public Auwai benchmark endpoint and no public host default in the runners. See local replication for the exact commands, the deterministic mock server, and the release gates.
The 1.0 evidence is in results:
- v6 matrix: 96/96 cells, all parseable;
- Auwai plus knowledge: 48/48 cells at 64/64;
- knowledge coverage: 1.00;
- workflow probes: 12,800 findings and claims, 796 stable facts.
Security
Read security before exposing the knowledge service beyond loopback. It covers the threat model, token scopes, request limits, TLS, and the release checklist.
Companions
- codebase memory is an optional symbol graph and ADR bridge. Required: no.
- A skill-aware gateway is optional. Required: no.
Neither is required for the index, the ledger, or the full-read path.
Current status
- The coverage ledger, partition tree, segment planner, full-read orchestrator, deterministic query, native watcher, raw-read policy, workspace survey, and workspace full read are released.
- A changed-path sync updates only the affected chunks and takes about 1 to 2 seconds at kernel scale. The full watcher path took 16.9 seconds.
- A local answer-quality run on Auwai itself scored 30 of 32 rubric points on
an eight-question set; the record is under
benchmarks/quality/results/. - The four harness plugins pass the parity and hook-vector suite.
- The knowledge service migrates SQLite, PostgreSQL, MySQL, and MariaDB schemas without losing facts, findings, claims, reads, or sync events.
- Stage 9 validation scored 30/32 with Auwai and 28/32 with a vanilla control on the same eight-question set, plus a full 64K segment with resolved citations.
- Stage 10 adds inotify on Linux, FSEvents on macOS, a polling fallback, and a workspace full-read runner with its own coverage ledger.
License
MIT.
Support Auwai
Auwai is MIT licensed. This project and the other projects in this account are committed to MIT. They are fully open source, free to use, modify, and distribute without a paid tier or restriction. The license notice remains the only condition. If the work is useful, you can buy me a coffee.