A live map of your system: its parts, its data, its plans and its agents, read from your repo.
Install · First run · How to use it · FAQ · Changelog
System Map is an app for Kiro Crew, the open-source personal AI agent.
Status: early. The model format may change, and the app upgrades it when it starts.
System Map adds a System Map page to Kiro Crew, and a tab in the chat side panel. It builds one model of a project from its repo's main branch: the modules and how they link, every table and foreign key, what your specs promise, where code is risky, what each worktree is changing, and which agents you run. Every view reads that model, and so can your agents, through small MCP tool calls instead of the whole thing.
It only reads your repo. It never writes to it, never runs your code, and never runs your tests.
A design chat goes stale the moment the code moves, and the design itself is spread across chats, docs, specs and branches. An agent asked about the system either reads the whole repo, which fills its context, or guesses.
System Map keeps one model, rebuilt from the repo, that a person can look at and an agent can query
in slices. Each number in it is held to the tool that owns it: the TypeScript compiler, real
Postgres, real SQLite, next build, git.
You open a project you haven't seen in weeks, or one someone handed you. The Map shows it at three levels: areas, the modules in an area, then one module with what it touches. Data model draws every table and foreign key. Findings lists rule checks, such as a table without row level security, each with its file and line.
Risk ranks code that changes often, has many paths and few tests, worst first. Worktrees shows what each worktree is changing, live, and where two of them conflict, from a real trial merge. Explore lets you describe a change, and the Design chat drafts a proposal: a diff against today, what Postgres will refuse, and what breaks. Nothing touches your repo.
Point the Agents tab at the list of your agents, or press Find my agents and the Design chat drafts that for you to check. It shows what starts each one, who it hands work to, which models it calls, and where it waits for a person. Set where each service runs and a home region, and any agent whose model runs elsewhere becomes a finding, with the line that calls it.
Screenshots show a made-up bookshop, taken from ui/dev, the stand-in host described in
docs/development.md. In Kiro Crew the page
sits inside the dashboard.
From the Kiro Crew App Store, once it is listed there:
- Open Apps → Discover in the left sidebar.
- Search for System Map and choose Install.
- Kiro Crew asks you to trust the app to run its own code. System Map needs that: its backend and
its agent tools are small Python programs that read your repos and run git. Trust gives them the
same access Kiro Crew has. If you are happy with that, trust it. You can take it back later in
Settings → Security → Third-party apps. If Kiro Crew refuses with
app_execution_deniedinstead of asking, setagent.apps_allow_third_partytotruein its config. - Enable the app, then restart Kiro Crew once (
kirocrew restart), so new sessions get its agent tools. A restart stops any work running in your sessions.
From a local clone:
(cd ui && npm install && npm run build)
kirocrew app install "$PWD"
kirocrew app enable system-map
kirocrew restartWhat you need:
- Kiro Crew on a Mac or Linux computer. WSL counts as Linux.
python3on thePATH. Everything runs on its standard library. It is tested on Python 3.12.git2.38 or later, for trial merges in Worktrees. With an older git, a merge reads as unknown.- To pick a folder with Browse: macOS,
zenityorkdialogon a Linux desktop, or Windows through WSL. - No account, key or network.
Open System Map from Apps in the sidebar. With no project yet, it asks you to add one. Choose Add project, pick a folder from your default folder or Browse for one, and the app builds its first model. That takes seconds for a small project, longer for a big one.
The project menu in the header adds, switches and removes projects. One is open at a time, and each keeps its own view and Design chat.
Each tab reads the same model.
- Map. Areas, then modules, then one module with what it touches. Links come from real imports and table calls. The Risk, Worktrees and Agents layers draw those views on the map.
- Data model. Every table and foreign key. Click a table to see only it and its neighbors.
- Plan. What your specs promise and what does not exist yet. Each status shows its evidence, and you can override any status.
- Risk. Code that changes often, has many paths and few tests, worst first. It works from imports alone. Load report adds a coverage report for real numbers, and Run tests in chat asks the Design chat to make one in a scratch copy. The app never runs your tests itself.
- Worktrees. What each worktree is changing, and where two of them conflict. Two worktrees on one table raise a warning.
- Findings. Rule checks, each with its file and line.
- Agents. Open Agent settings and name the file that lists your agents, or the modules to
treat as agents, and the names your code uses for model calls, hand-offs and asks-you calls. The
app never guesses: an agent comes from the list you name or a module you mark. Show on map
finds an agent on the Agents layer.
- Find my agents: the Design chat reads your code and drafts the settings, with the lines it read them from. You see what they find, then use them, edit them first, or drop them.
- Explore.
- What if: describe a change, and the Design chat drafts a proposal. You get a diff against today, what Postgres will refuse, what breaks, draft SQL, and which use case gaps it closes.
- Use cases: map what someone needs to do to its routes, tables and tests.
- Views: ask for a picture in chat, and the app draws and keeps it.
- Design chat. A chat beside the map, and an Ask button on everything.
- Side panel. Open System Map in a chat's side panel to browse the same model there.
- Agent tools. Any session can read the model through MCP tools, starting with
overview. Tools that read are approved for you. Tools that write, such asnoteandpropose, ask first.
| Part | Read from |
|---|---|
| Postgres | Migrations in supabase/migrations, db/migrations or migrations |
| SQLite | Any .sql file, including what Prisma and Drizzle generate, CREATE TABLE inside code, or a Drizzle schema in TypeScript. Real SQLite reads it, in memory |
| Routes | Next.js App Router and Pages Router, TanStack and Remix file routes |
| Code | TypeScript and JavaScript, with paths and baseUrl from tsconfig.json or jsconfig.json |
| Jobs | cron.schedule calls in SQL |
| Plans | docs/specs, docs/plans, specs, and a BRIEF, PLAN, ROADMAP, PRD, SPEC or TODO file at the top of the repo |
| Agents | Agents declared with the OpenAI Agents SDK (@openai/agents), Mastra (@mastra/core) or the Claude Agent SDK (@anthropic-ai/claude-agent-sdk), with no settings, when the root package.json lists the SDK. Hand-offs between OpenAI Agents come from handoffs. And the exported list you name in the Agents tab, or modules you mark, or a draft from the Design chat that you use. Hand-offs, model calls and calls that ask a person are found by the names you give there. A hand-off is a property, as in { agent: "mail" }, or a call whose first argument names the agent, as in queueAgent("mail", id). Jobs start an agent when their cron.schedule command, or the SQL function it calls, names it |
| History | Git history and worktrees. Coverage reports from Vitest, Jest or anything that writes lcov |
A project needs no git history, though Risk has no churn without it, and there are no worktrees.
Add project lists git repos and any folder with a package.json. Use a full path for anything else.
Each build records what it read, and the status menu shows it. If a build finds something it can't read, it names it: a Prisma schema with no SQL migrations, a Drizzle schema for anything but SQLite, any part of a Drizzle schema that only running it could answer, MySQL, MongoDB, or a Next.js app in a subfolder.
A Drizzle schema is read as text and never run. SQL files win where a project has both, since they are what the database ran. Code links to Drizzle tables either way.
Run your tests yourself, then press Load report on the Risk view, or use the coverage tool.
Without a report, Risk still shows which tests reach each file. With Vitest, list every source file
in coverage.include, or a file no test loads will be missing from the report. System Map counts a
missing file as 0%.
- Where data lives. In the app's own data folder,
$KIROCREW_HOME/apps/system-map/data(~/.kiro/crew/apps/system-map/databy default).SYSTEM_MAP_DATApoints it somewhere else. - What it keeps. Each project's model, with its last 5 versions. Your own input sits beside it and survives rebuilds: plan status overrides, agent settings, service regions, proposals, use cases, saved views and notes, and the coverage report you loaded.
- What it never does. Write to your repo, run your code, or make a network call of its own. The Design chat is an ordinary Kiro Crew chat, so it talks to your model as any chat does.
- What an agent can and can't do through the backend. The backend asks the gateway who is
calling (
backend.signedPrincipal). A caller that isn't a person in the dashboard, such as an agent or tool, can read the built models, rebuild a project already listed, and load a coverage report. It can't set anything in the Intent layer: agent settings, a service's region, a plan's status, using or dropping an agent draft, or accepting or dropping a proposal. It also can't build a folder it names, remove a project, set the default folder, browse or list folders, or open the folder window. Those answer 403. - Removing a project deletes its app data for good. It never touches the repo.
- Uninstalling keeps the data folder.
kirocrew app uninstall system-map --purge-datadeletes it too, and can't be undone. - Permissions it asks for.
/apps/system-map/apifor its own backend;/api/chatand/api/chat/slotsto open each project's Design chat;/api/recent-projectsto suggest a default folder, which it skips if refused; andstorage, since it keeps that data folder.
Agent sessions don't have the System Map tools. After a first install, restart Kiro Crew
(kirocrew restart). A new session alone doesn't help: the gateway only adds the tools to the agent
spec when it boots. Tools appear as mcp__system-map_system-map__<tool>.
The page says a request did not come through Kiro Crew. The backend only answers calls the gateway signs with the app's secret. Something called it directly, or the gateway has no secret for the app. Sync or reinstall the app, then restart Kiro Crew.
The page can't reach the backend. The backend runs only once you trust the app. Check Settings → Security → Third-party apps, then reload the page.
Browse does nothing. On Linux the folder window needs a desktop and zenity or kdialog.
Without one, type the full path instead.
My latest changes don't show. A git repo is read at its main branch's last commit, so uncommitted work and other branches don't show. Worktrees shows what each worktree is changing.
A build says it couldn't read part of the project. Some stacks aren't read yet, and the build names each one rather than guessing. The status menu lists what it read.
Worktree merges show as unknown. Trial merges need git 2.38 or later.
I updated the app, but nothing changed. In Apps → Library, open System Map's details and choose Sync, then reload the page. A new tool reaches new sessions only.
The code layout, the checks, running the page without Kiro Crew, and how to prove each reader against the real tool are in docs/development.md. The checks in short:
python3 tests/strict.py
(cd ui && npm test && npm run typecheck && npm run build)To fix an issue, read CONTRIBUTING.md first: claim the issue before you start.
Apache-2.0