Avagahana
See how it all connects.
Your agent writes a map in plain Markdown. You read it as a diagram you can explore,
at your own pace. Avagahana (Telugu: అవగాహన) means understanding.
Watch the video ·
Read the article ·
Gallery ·
Install ·
Map format ·
Viewer API ·
Changelog
Quick install
In Claude Code:
/plugin marketplace add nvsravank/avagahana
/plugin install avagahana@avagahana
Codex, local checkouts and the maps folder: see Install.
If Avagahana helps you, a star on the repo helps others find it.
What you can do with it
- Map a codebase with your coding agent: one linked map of how the system works.
- Explain and revise in conversation: the agent draws a concept and redraws as you talk.
- Explore an architecture from context to containers to components.
- Follow a request across components, played over the structure it runs on.
- Walk a lifecycle through its states and transitions.
- Explain database grain, cardinality and joins, and how a SQL query is built.
- Review a release, migration or pull request as a picture of what was added, changed
or removed.
- Keep a personal visual reference that shows what changed since you last looked.
- Deliver a narrative explainer as a walkthrough for an audience.
- Send an explorable file: one HTML file that opens offline.
- Put a branded figure in a document as SVG or PNG in your own theme.
- Keep it all on your machine: maps are local files.
Let the agent draw
Ask your agent to explain something. It writes a map in Markdown and Mermaid, text it
already knows, never an image. You see the picture, and it redraws as the file changes.
Two skills come with it: illuminate-concept for one idea, trace-architecture for a
whole repository. A strict checker finds the mistakes in a map before you open it.
See the whole
Begin with the whole system, then open it one level at a time: its parts, then
everything inside. Or read the same map as an outline, by keyboard or screen reader.
Go one level deeper
Step into one box and the world around it stays in view, faded. Every part has a page
of its own: what it connects to, the views it appears in, where it runs in each
environment.
Watch it move
A sequence plays on the diagram it happens in, one message at a time. Here two
readers miss the same cache entry at the same moment, and the database is asked
twice.
See it play,
then the quieter way: one reader rebuilds, the others wait.
Know what to trust
Not everything an agent explains is equally certain. Each box and arrow can say how
sure it is: verified, inferred, a hypothesis, or unsourced.
Notice what changed
Come back to a map and a small button says what changed since you last looked, for
you alone. A planned change marks what is added, changed and removed; Before and
After lays two versions on the same picture.
Follow a thing through its life
Step an order through its states, one step at a time. Step a query through its tables,
with a warning where a join multiplies rows.
Make it yours
Two colours and a font become a theme, in light and dark. Any view renders to SVG or
PNG for a document or a slide.
Carry it with you
Pack a map into one HTML file, the viewer inside it. It opens anywhere, with no server
and no network.
Avagahana is a reader by design: a map changes when its text changes. There is no
MCP server, and no comments or shared editing.
Install
Python 3.9+ is required; a maintained, patched Python is recommended. Tested on 3.9
and 3.15. Standard library only: no virtual environment or package installation.
The relay listens on 127.0.0.1 for local single-user use. See
local operation and data boundaries for platform and file-access details.
The plugin carries its version (version in .claude-plugin/plugin.json and
.codex-plugin/plugin.json; see the changelog). Claude Code and Codex
notice an update when it changes; each version is also a git tag vX.Y.Z.
Claude Code
/plugin marketplace add nvsravank/avagahana
/plugin install avagahana@avagahana
For a local test, add the checkout path instead of the GitHub name, or start
claude --plugin-dir /absolute/path/to/avagahana/repo.
Codex
codex plugin marketplace add nvsravank/avagahana
codex plugin add avagahana@avagahana
For a local test, replace nvsravank/avagahana with the absolute checkout path.
You can also install from the Avagahana source in the app's plugin browser.
Start a new chat after installation. Remove an old Sphuta installation to avoid
loading both skills.
Maps folder (shared by both clients)
On first use, the skill asks for an existing maps folder and saves its absolute path
in ~/.config/avagahana/maps-dir. To set or change it yourself:
mkdir -p ~/.config/avagahana
printf '%s\n' '/absolute/path/to/maps' > ~/.config/avagahana/maps-dir
AVAGAHANA_MAP_DIR, when present in the agent's command environment, overrides that
file. No maps are stored in the plugin or moved during installation. Standalone
relay commands still accept --maps-dir or AVAGAHANA_MAP_DIR.
See docs/deploy-targets.md for the package layout.
Components
Each part works alone and is tested alone.
| Folder | What it is | Runs alone as |
|---|
map-viewer/ | Embeddable, read-only map viewer. Plain ES modules. | import { mount } from './map-viewer/index.js' in any page; no server needed. |
atlas/ | The first page: lists maps from a source, hosts the viewer, owns the URL. | Open atlas/index.html and pick a folder (Chromium), or let the server serve it. |
relay-server/ | Optional local server, Python 3.9+ standard library. Serves maps and pushes updates. | python3 relay-server/serve_maps.py --maps-dir <folder> |
Also here: format/ (the map format and checker), skills/ (the shared agent
skills), examples/ (sample maps and an embed example), and docs/ (the contracts).
The repository itself is the plugin: one copy of each component, no build step.
Contracts
Validation
Run bash scripts/validate.sh for dependency, format, plugin, relay and browser
checks. Chrome, Chromium or Edge is required; set AVAGAHANA_CHROME to its
executable when not discovered automatically. CI runs this command on pushes and
pull requests. scripts/check.sh is the lightweight pre-commit check: the dependency
rule between parts, and the clean check. No build step; standard library only for
Python.
Licence
MIT. See LICENSE.
