astos

A code-map for AI agents. astos scans your repository into a dependency graph once, then answers the questions your AI agent keeps burning tokens on — cheaply, with file+line citations.

$ astos debug
ASTOS debug :: 12 arquivo(s) sujo(s) no git — ordem de leitura (entrypoints: astos/cli.py):
- astos/cli.py [M] +106/-26 deg=6 · quem chama: `tests/test_cli.py`:11 ...
- astos/queries.py [M] +214/-35 deg=6 · chama: astos/parser.py:118

Left: real terminal output, verbatim. Right: the offline 3D map of astos itself.

The proof (measured, reproducible)

Same bug-hunt question, same repo, same answer — 10× less context fed to the agent. Repo: psf/requests @ 611c616 (200 files). Question: "where does the user-configured timeout actually get applied?" Answer: src/requests/adapters.py :: HTTPAdapter.send (TimeoutSauce at line 684). Both policies find it.

10.0× less context, identical answer. Tokens estimated at bytes/4 (the standard proxy). The naive policy is the deterministic grep-and-read pattern agents use without a map; astos's side counts every byte an agent would see. Reproduce it yourself:

pip install astos
python3 bench/benchmark.py   # clones requests, scans, measures, saves results.json

Quickstart

pip install astos
astos          # full scan → .astos/ (3D map + graph) + AGENTS.md block
astos -f       # fast refresh (mtime cache; no browser)
astos debug    # where's the bug? dirty files ranked, with callers at line N

That's it. Open the .astos/index.html (works 100% offline, no server) or let your agent read AGENTS.md — the block there is maintained automatically and is the cheapest context your agent will ever get.

What your agent gets

AGENTS.md gains a surgically-maintained block: file map, dependencies, hubs, risks, capabilities, entry points. Then 14 queries answer the rest without re-reading source:

There's also an MCP server (astos mcp --path .) exposing the same queries as agent tools — no shell needed.

Capabilities: who talks to which hardware

25 capability categories detected from real code APIs, manifests and dependency files: camera, microphone, location, bluetooth, usb, serial, gpio, i2c, spi, keyboard, gamepad, vibration, sms, contacts, health, motion, biometrics, nfc, telephony, sensors, storage, notifications, screen, media, network.

$ astos q --cap camera
ASTOS q :: 1 hit(s) (ordenado por grau)
- `app.py` deg=0 lang=python caps=camera
manifest: `manifest:AndroidManifest.xml[CAMERA]`

Sources it reads: AndroidManifest.xml permissions, iOS Info.plist (NS*UsageDescription), UWP .appxmanifest, package.json / Cargo.toml / go.mod / pubspec.yaml / Gradle / Podfile dependency names — plus API usage inside code (e.g. cv2.VideoCapture, navigator.serial, SensorManager, input.location). stdio-noise control: docstrings and comments don't count as usage; a "camera dictionary" file that merely mentions every capability gets filtered out by density.

How it works

• 13 language parsers (Python, JS/TS, Dart, Kotlin, Java, Go, Rust, C/C++, C#, PHP, Ruby, Swift, generic) — pure stdlib; no tree-sitter, no LSP.
• Call edges are heuristic (name matching) — good enough to rank, cited with the exact call-site line so the agent can verify.
• Incremental cache: astos -f re-scans only changed files (mtime+size).

For this repo's own contributors

pip install -e . && pip install pytest
python3 -m pytest            # 46 tests
bench/benchmark.py           # measure token savings yourself
bench/make_gifs.py           # regenerate docs/img/*.gif

PT-BR: README.pt-BR.md

License

MIT