AikiMap is a read-only repository map for coding-agent sessions. It shows working-tree changes and recent commits as a treemap, updates as files are saved, and lets you inspect file diffs without changing Git state.
- Each rectangle represents a tracked file.
- Folder size reflects the number of files it contains—not lines of code or complexity.
- Working Changes opens first and includes staged, unstaged, and untracked files.
- Changed folders are highlighted so you can locate affected areas quickly.
- A live AikiBot marker shows the file currently being edited. In commit history, persistent AikiBot markers identify the files changed by the selected commit.
- Commit History lets you inspect up to 10 recent commits.
- The branch label identifies the current checkout. History branch lets you browse local and fetched remote branches without switching your Git checkout; Working Changes always shows the current checkout.
- Selecting a file turns its box into an inspector showing exact state and line totals; Show Diff loads its read-only patch inside that box on demand.
- Live and native modes keep one history map loaded at a time to reduce WebView work on large repositories.
| Colour | Meaning |
|---|---|
| Cool grey | Unchanged |
| Pale lavender | Folder contains changes |
| Muted teal | Added |
| Amber | Modified |
| Coral | Deleted |
| Indigo | Renamed |
You need Python 3.10 or newer and Git on your command line.
git clone https://github.com/anielhub-guru/aiki-map.git
uv tool install /path/to/aiki-mapThis installs from the downloaded folder. It does not use or publish to PyPI. If
you prefer pipx, use pipx install /path/to/aiki-map.
When the local checkout changes, update the installed command with:
uv tool install --force --reinstall-package aikimap /path/to/aiki-mapFor Codex IDE, install the AikiMap skill once after installing the command:
aikimap install-codexThen, in a local Codex coding chat, invoke $aikimap or ask it to open AikiMap.
The agent runs AikiMap in a separate process and the corner window appears
without opening an external terminal. OpenAI documents $skill-name as the
supported explicit invocation in the Codex IDE extension; custom slash prompts
are deprecated.
For VS Code, Cursor, Antigravity, or another IDE agent that can run a local command, ask it to run this for the current Git repository:
aikimap ide --detach --repository /absolute/path/to/projectThe equivalent foreground command, useful in an integrated terminal, is:
aikimap ideThis opens AikiMap as a passive repository monitor. It does not launch a second Codex process, so continue working through the IDE's normal agent interface.
To wrap the terminal Codex CLI instead, run:
cd /path/to/project
aikimap codexFor Claude Code:
aikimap claudeArguments after the shortcut are passed to the agent:
aikimap codex --model your-modelAikiMap detects the current Git repository, records the baseline, and opens the corner window. Terminal-agent shortcuts then start the wrapped agent; IDE mode only monitors the repository.
For another terminal agent:
aikimap agent --source custom -- your-agent-command --its-argumentTo inspect a repository without launching an agent:
aikimap view /path/to/repositoryAikiMap starts a local server and opens the view. Working changes refresh every 2.5 seconds. Repeated saves to an already-modified file trigger an EDITING pulse, a highlighted map tile, and an animated robot face over that file.
To start the server without opening a browser automatically:
aikimap view /path/to/repository --no-openTo generate the original standalone file instead of running live mode:
aikimap view /path/to/repository --staticUse --repository /path/to/repository when launching outside the worktree. Use
--browser for remote, headless, or dependency-limited environments:
aikimap agent --source codex --repository /path/to/repository --browser -- codexThe native window uses the operating system webview on macOS, Windows, and Linux. Linux systems may need their distribution's WebKitGTK runtime. If the native webview cannot start, AikiMap falls back to the default browser and prints the local review URL.
The wrapper commands are intended for terminal agents. GUI editors use
aikimap ide, which observes repository activity without controlling the IDE
process.
Aiki Map observes the working tree and committed Git history without modifying the
repository it inspects. It does not stage files, create commits, switch branches,
restore files, or change Git configuration. Live mode binds only to 127.0.0.1,
so repository data remains on the local computer.
- Read the current staged, unstaged, and untracked file states.
- Read and cache metadata for the latest 10 commits.
- Build the repository hierarchy from tracked files and current additions.
- Check the working state every 2.5 seconds through a local endpoint.
- Compare file timestamps and sizes with the preceding refresh to detect saves.
- Pulse and highlight files being edited, including files already marked modified.
- Build and display one selected history map at a time, with persistent AikiBot markers on the changed files.
- Read one validated file diff only when Show Diff is selected.
- Optionally wrap an agent process and expose its session state locally.
Common dependency, build, cache, and editor directories are filtered from the map so that application structure remains visible.
The current MVP combines all working changes in one map and keeps committed history as a secondary view. It does not animate treemap geometry, show side-by-side comparisons, edit files, or connect a change to the AI instruction that caused it.
