walnut-manage-repos · diff
git:20260527.3970344 to git:20260911.35d897a
22 added, 18 removed. Audit A to A.
---
name: walnut-manage-repos
description: >-
Manage repository profiles — add, view, edit, or remove registered repositories.
Each repo stores name, description, tech stack, host paths, architecture notes,
and common commands as structured YAML.
Use when user says "add repo", "manage repos", "register repository",
"show my repos", "edit repo", or wants to manage repository profiles.
---
# Manage Repositories
- You manage repository profiles using the `file_*` tools with the `repos/` URI prefix.
- Repository data is stored as YAML files in `~/.open-walnut/repositories/`.
+ Repository profiles are YAML files in `~/.open-walnut/repositories/`, one per repo, served
+ by the `/api/repositories` routes. Reach them through the `api` operation, which is the
+ passthrough for an endpoint with no named operation of its own.
## Available Operations
### List all repositories
```
- file_list prefix='repos'
+ walnut tools call api '{"method":"GET","path":"/api/repositories"}'
```
### Read a repository's full profile
```
- file_read source='repos/{name}'
+ walnut tools call api '{"method":"GET","path":"/api/repositories/{slug}"}'
```
- ### Create a new repository
+ ### Create or replace a repository
+ A POST replaces the whole file, so send the complete YAML, not a fragment.
```
- file_write source='repos/{name}' content='...'
+ walnut tools call api '{"method":"POST","path":"/api/repositories/{slug}","body":{"content":"name: …\n…"}}'
```
### Edit an existing repository
- ```
- file_read source='repos/{name}' # get content_hash first
- file_edit source='repos/{name}' old_content='...' new_content='...' content_hash='...'
- ```
+ Read it first and edit the text you got back, then POST the whole thing. Editing the file
+ directly with your own Read/Edit tools works too, and is easier for a long profile.
### Delete a repository
- Ask the user to delete it from the Repos page in the UI, or use shell_exec:
```
- shell_exec command='rm "$HOME/.open-walnut/repositories/{name}.yaml"'
+ walnut tools call api '{"method":"DELETE","path":"/api/repositories/{slug}"}'
```
## YAML Format
When creating or updating a repo, use this YAML format:
```yaml
name: Project Name
description: Brief one-line description of the project
tech_stack: [TypeScript, React, Node.js]
hosts:
local:
path: /Users/me/code/project
cloud-desktop:
path: /home/me/project
ssh_host: dev-desktop
overview: |
What: A web application for managing tasks
Why: Help users organize work across projects
How: React frontend with Express API and SQLite storage
architecture: |
Frontend: React SPA with Vite (web/src/)
Backend: Express REST API (src/web/)
Storage: SQLite via better-sqlite3
- Key dirs: src/core/ (business logic), src/agent/ (AI integration)
+ Key dirs: src/core/ (business logic), src/model/ (model calls)
architecture_notes: |
Frontend: React SPA (web/src/)
Backend: Node.js + Express (src/)
Database: SQLite for local data
common_commands: |
npm run build # Build the project
npm run dev # Development mode
npm test # Run tests
```
### Required Fields
- **name**: Human-readable project name
- **description**: One-line summary
- **hosts**: At least one host entry with a `path`
### Optional Fields (rich profile)
- **tech_stack**: Array of technologies
- **overview**: What/Why/How summary (auto-generated by /register-repo)
- **architecture**: Detailed architecture breakdown (auto-generated by /register-repo)
- **architecture_notes**: Brief architecture description (legacy, use `architecture` for new repos)
- **common_commands**: Multi-line list of useful commands
- **ssh_host**: SSH hostname for remote hosts
## Workflow
When user asks to add/register a repository:
1. Ask for the repo name and path (or infer from context)
2. Ask for description and tech stack
3. Generate the YAML content
- 4. Write with `file_write source='repos/{slug}'`
+ 4. POST it to `/api/repositories/{slug}` through the `api` operation
5. Confirm creation and show the profile
The slug (filename) should be lowercase, hyphenated (e.g., "my-project").
- ## Context Injection
+ ## Where a profile is read
- Registered repositories are automatically:
- - Listed in the main agent system prompt (name + description + hosts)
- - Matched by CWD when starting Claude Code sessions — matched repos inject architecture/commands as `<repository_context>` into the session
+ A profile is data, not an automatic prompt injection. Nothing puts it into a session's
+ system prompt: it is served to the Repositories page in Settings and to the library API,
+ and it is read on request through the `api` operation above, which is how you should reach
+ it when a task names a repo you do not know.
+
+ So write a profile for a human and for an on-demand read, and put anything a session must
+ know unprompted in that repo's own `AGENTS.md` / `CLAUDE.md` or in a skill, which the
+ session does load.