Skip to content
anielhub-guruPublic

About

Live, read-only Git maps for coding-agent sessions

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Aiki Map

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.

Aiki Map visualizing a modified file in a mock repository

What the map shows

  • 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

Install locally

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-map

This 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-map

Launch with a coding agent

For Codex IDE, install the AikiMap skill once after installing the command:

aikimap install-codex

Then, 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/project

The equivalent foreground command, useful in an integrated terminal, is:

aikimap ide

This 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 codex

For Claude Code:

aikimap claude

Arguments after the shortcut are passed to the agent:

aikimap codex --model your-model

AikiMap 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-argument

To inspect a repository without launching an agent:

aikimap view /path/to/repository

AikiMap 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-open

To generate the original standalone file instead of running live mode:

aikimap view /path/to/repository --static

Use --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 -- codex

The 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.

Read-only by design

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.

How it works

  1. Read the current staged, unstaged, and untracked file states.
  2. Read and cache metadata for the latest 10 commits.
  3. Build the repository hierarchy from tracked files and current additions.
  4. Check the working state every 2.5 seconds through a local endpoint.
  5. Compare file timestamps and sizes with the preceding refresh to detect saves.
  6. Pulse and highlight files being edited, including files already marked modified.
  7. Build and display one selected history map at a time, with persistent AikiBot markers on the changed files.
  8. Read one validated file diff only when Show Diff is selected.
  9. 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.

Current scope

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.

About

Live, read-only Git maps for coding-agent sessions

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages