nhcarrigan/hikari-desktop
9
0
Fork 0
generated from nhcarrigan/template
Code Issues 9 Pull Requests 36 Actions Releases 22 Activity

feat: codebase mapper (auto-generate architectural summary for Claude's context) #190

New Issue
Closed
opened 2026-03-06 09:38:37 -08:00 by hikari · 0 comments
hikari commented 2026-03-06 09:38:37 -08:00
Owner
Copy Link
Copy Source

Overview

Inspired by get-shit-done (GSD)'s /gsd:map-codebase command, this adds a Codebase Mapper — a tool that analyses the current project's structure and generates a concise architectural summary that can be injected into Claude's context before planning or executing tasks.

The Problem: Architectural Blindness

When starting a new feature or jumping into an existing codebase, Claude often lacks awareness of the project's conventions, architecture patterns, key files, and tech stack. This leads to suggestions that don't fit the codebase style, missed existing utilities, and inconsistent patterns.

Feature Details

What It Generates

The mapper analyses the working directory and produces a CODEBASE.md file covering:

  • Project overview — detected tech stack, frameworks, and languages
  • Directory structure — annotated tree of key directories and their purpose
  • Key files — identified entry points, config files, and core modules
  • Conventions — detected patterns (naming conventions, test file locations, import styles)
  • Dependencies — summary of major runtime and dev dependencies
  • Build & test commands — detected from package.json, Makefile, etc.

How It Works

  1. Scans the working directory tree (respects .gitignore)
  2. Reads key files (package.json, Cargo.toml, pyproject.toml, README, etc.)
  3. Sends a structured analysis prompt to Claude Code
  4. Claude generates the CODEBASE.md summary
  5. Summary is saved and made available for injection into future prompts

UI

  • "Map Codebase" button in the toolbar or Project Context Panel (#188)
  • Progress indicator whilst Claude analyses the project
  • Generated CODEBASE.md displayed in the Project Context Panel
  • "Inject into next prompt" toggle to prepend the map to the next conversation
  • "Auto-inject for Task Loop" setting to prepend CODEBASE.md to every task loop iteration
  • "Regenerate" button to refresh the map after major changes

Integration Points

  • Integrates with the Project Context Panel (#188) — CODEBASE.md is a managed file alongside PROJECT.md and STATE.md
  • Automatically suggested at the start of the Guided Workflow (#189) Discuss phase
  • Task Loop (#183) can optionally include CODEBASE.md as context for each task

Supported Project Types

Auto-detect and handle:

  • Node.js / TypeScript (package.json)
  • Rust (Cargo.toml)
  • Python (pyproject.toml, requirements.txt)
  • Generic (README, directory structure)

Acceptance Criteria

  • "Map Codebase" action triggers analysis of the working directory
  • Generates a CODEBASE.md with architecture summary, key files, and conventions
  • Respects .gitignore when scanning the directory tree
  • CODEBASE.md is viewable and editable in the Project Context Panel
  • Can be injected into the next prompt manually
  • Auto-inject option for Task Loop iterations
  • Works for Node.js, Rust, and Python projects at minimum
  • Tests written for file scanning logic and project-type detection

✨ This issue was created with help from Hikari~ 🌸

## Overview Inspired by [get-shit-done (GSD)](https://github.com/gsd-build/get-shit-done)'s `/gsd:map-codebase` command, this adds a **Codebase Mapper** — a tool that analyses the current project's structure and generates a concise architectural summary that can be injected into Claude's context before planning or executing tasks. ## The Problem: Architectural Blindness When starting a new feature or jumping into an existing codebase, Claude often lacks awareness of the project's conventions, architecture patterns, key files, and tech stack. This leads to suggestions that don't fit the codebase style, missed existing utilities, and inconsistent patterns. ## Feature Details ### What It Generates The mapper analyses the working directory and produces a `CODEBASE.md` file covering: - **Project overview** — detected tech stack, frameworks, and languages - **Directory structure** — annotated tree of key directories and their purpose - **Key files** — identified entry points, config files, and core modules - **Conventions** — detected patterns (naming conventions, test file locations, import styles) - **Dependencies** — summary of major runtime and dev dependencies - **Build & test commands** — detected from package.json, Makefile, etc. ### How It Works 1. Scans the working directory tree (respects `.gitignore`) 2. Reads key files (package.json, Cargo.toml, pyproject.toml, README, etc.) 3. Sends a structured analysis prompt to Claude Code 4. Claude generates the CODEBASE.md summary 5. Summary is saved and made available for injection into future prompts ### UI - **"Map Codebase" button** in the toolbar or Project Context Panel (#188) - Progress indicator whilst Claude analyses the project - Generated CODEBASE.md displayed in the Project Context Panel - **"Inject into next prompt"** toggle to prepend the map to the next conversation - **"Auto-inject for Task Loop"** setting to prepend CODEBASE.md to every task loop iteration - **"Regenerate"** button to refresh the map after major changes ### Integration Points - Integrates with the Project Context Panel (#188) — CODEBASE.md is a managed file alongside PROJECT.md and STATE.md - Automatically suggested at the start of the Guided Workflow (#189) Discuss phase - Task Loop (#183) can optionally include CODEBASE.md as context for each task ### Supported Project Types Auto-detect and handle: - Node.js / TypeScript (package.json) - Rust (Cargo.toml) - Python (pyproject.toml, requirements.txt) - Generic (README, directory structure) ## Acceptance Criteria - [ ] "Map Codebase" action triggers analysis of the working directory - [ ] Generates a CODEBASE.md with architecture summary, key files, and conventions - [ ] Respects .gitignore when scanning the directory tree - [ ] CODEBASE.md is viewable and editable in the Project Context Panel - [ ] Can be injected into the next prompt manually - [ ] Auto-inject option for Task Loop iterations - [ ] Works for Node.js, Rust, and Python projects at minimum - [ ] Tests written for file scanning logic and project-type detection ✨ This issue was created with help from Hikari~ 🌸
naomi closed this issue 2026-03-07 03:08:34 -08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
aspect
code
Concerns the software code in the repository
aspect
dx
Concerns developers' experience with the codebase
aspect
interface
Concerns end-users' experience with the software
aspect
text
Concerns the documentation material in the repository
contribute
good first issue
A great opportunity for a team member to learn a new codebase
contribute
help wanted
Open for anyone on our team to grab.
contribute
staff only
Restricted to our executive leadership.
goal
addition
Addition of new feature
goal
fix
Bug fix
goal
improvement
Improvement to an existing feature
points
1
Very simple issue requiring minimal effort and complexity.
points
13
Extremely complex issue representing major undertakings. Should be broken down into smaller pieces.
points
2
Simple issue that requires a bit more thought or investigation.
points
3
Moderate complexity issue requiring more substantial work.
points
5
Complex issue requiring significant effort and expertise.
points
8
Very complex issue requiring extensive work and deep expertise.
priority
critical
1
Must be fixed ASAP
priority
high
2
Stalls work on the project or its dependents
priority
low
4
Low priority and doesn't need to be rushed
priority
medium
3
Not blocking but should be fixed soon
priority
none
5
No priority, should only be performed when a developer is available
status
awaiting triage
Has not been triaged & therefore, not ready for work
status
blocked
Blocked and therefore not ready for work
status
discarded
Will not be worked on
status
discontinued
Not suitable for work as repo is in maintenance
status
label work required
Needs proper labelling before it can be worked on
status
ready for dev
Ready for work
status
ticket work required
Needs more details before it can be worked on
talk
discussion
Open for discussions and feedback
talk
question
Can be resolved with an answer
time
1 day
Approximately one full day of development work.
time
1-2 weeks
One to two weeks of focused development effort.
time
2-3 days
Two to three days of development effort.
time
4-5 days
Approximately one week of development work.
time
<1 day
Less than one day of focused work. Quick fixes or simple tasks.
time
>2 weeks
More than two weeks of development work. Must be broken down into smaller pieces.
No Label
Milestone
No items
No Milestone
Assignees
Clear assignees
gurkirat hanna (Hanna Rose) hikari (Hikari) minori (Minori) naomi (Naomi Carrigan) rain teklu tim
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: nhcarrigan/hikari-desktop#190
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?