Muhammad Zakir Ramadhan
9b978fdbe1
Most of this replaces "roughly 550 characters per tool" with the actual per-tool measurements, and fills in the parts a reader hits after the happy path: what a specific error means, what a setting costs, what is not covered. Measured rather than estimated: - Per-tool byte cost, all fourteen, and the per-set totals. 7,673 B for the full set, averaging 548. - Builtin skill bodies at 5,284 B against a 681 B catalogue, which is the argument for loading bodies on demand. - Full system prompt 3,571 chars, core-only 2,045. New sections: - tools: which sets to keep and why, the jail function itself, an output-cap table, and the real error strings for edit_file and multi_edit. - configuration: env var per provider preset, cost-estimate limits, what each --no-* flag isolates, and three settings that do more than they look like. - agents: step caps per variant, which variant to reach for, and the fact that reasoning is charged as output and discarded first by compaction. - headless: exit code 0 means "the turn completed", not "the answer was yes" — with the jq pattern for gating on content. Timeouts, concurrent -c runs fighting over one session, CI recipes for --no-skills. - mcp: parallel connect, startup cost, a debugging ladder, and that toolSets does not gate MCP tools. - registry: publishing, local testing over http://localhost, and a troubleshooting section keyed on the actual validator messages. - memory: what compaction discards in what order, /compact versus automatic pruning, and that -c matches on cwd. - skills: the frontmatter reader's limits, and how to verify a skill loaded. Corrections found while cross-checking against the source: - The guard table was missing --force-with-lease and > /dev/sd… - The done event's token fields are optional, so the jq example filters on one rather than assuming it. Two honest limits now written down: the guard matches command strings, so a base64-decoded or script-wrapped command is not caught; and a registry index is trusted for its contents, not its authorship. Verified: all internal links and heading anchors resolve, every docs/ page is reachable from the README, 538 tests pass, typecheck clean.
157 lines
6.5 KiB
Markdown
157 lines
6.5 KiB
Markdown
<p align="center">
|
|
<img src="./assets/logo.png" height="300">
|
|
</p>
|
|
|
|
<h1 align="center">Shiro Neko</h1>
|
|
|
|
<p align="center">
|
|
An agentic coding CLI. It reads your code, edits it, runs your tests, and asks when the
|
|
request is ambiguous — in a terminal UI, with every mutating action gated behind an
|
|
approval prompt.
|
|
</p>
|
|
|
|
|
|
## Install
|
|
|
|
A single prebuilt binary. No runtime, no `node_modules`.
|
|
|
|
```bash
|
|
# macOS, Linux
|
|
curl -fsSL https://raw.githubusercontent.com/zakirkun/shiro-neko/main/scripts/install.sh | sh
|
|
|
|
# Windows
|
|
irm https://raw.githubusercontent.com/zakirkun/shiro-neko/main/scripts/install.ps1 | iex
|
|
```
|
|
|
|
Both verify the download against the release checksums before installing. Builds are
|
|
published for `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, and `windows-x64`.
|
|
|
|
Or from source:
|
|
|
|
```bash
|
|
git clone https://github.com/zakirkun/shiro-neko
|
|
cd shiro-neko
|
|
bun install
|
|
bun run install:local # builds and puts `shiro` on PATH
|
|
```
|
|
|
|
## First run
|
|
|
|
```bash
|
|
shiro
|
|
```
|
|
|
|
With no API key configured it opens provider setup: pick an endpoint, paste a key, choose
|
|
from the models that endpoint actually reports. Settings land in
|
|
`~/.shiro-neko/config.json`. Run `/provider` any time to change them.
|
|
|
|
```
|
|
shiro-neko 0.1.0-beta.3 openai/gpt-5 session 0193ab2c
|
|
agent: default thinking: medium
|
|
cwd: /home/you/project
|
|
skills: debug, refactor, review, test
|
|
plugins: guard, time
|
|
approvals: on for write_file, edit_file, multi_edit, bash, mcp__*
|
|
/help for commands
|
|
|
|
> why does the pagination test fail?
|
|
```
|
|
|
|
## What it does
|
|
|
|
**Answers about your code, grounded in your code.** `grep` goes through ripgrep when it is
|
|
installed and honours `.gitignore`. `list_dir` gives an ignore-aware tree so it stops globbing
|
|
blindly to orient, and `read_many_files` pulls a batch in one round trip. `read_file` refuses
|
|
binaries rather than filling the context with mojibake.
|
|
|
|
**Edits with your approval.** Every `write_file`, `edit_file`, `multi_edit`, and `bash` call
|
|
stops for a `y`/`a`/`n` decision, with a coloured diff for edits. `multi_edit` is atomic, so
|
|
a failing match leaves the file untouched rather than half-changed. The `guard` plugin
|
|
refuses irreversible commands outright — `rm -rf`, `git reset --hard`, force pushes,
|
|
`DROP TABLE` — and `--yolo` cannot bypass it.
|
|
|
|
**Shows its work.** Reasoning streams to a collapsed panel you can expand with `ctrl-r`, the
|
|
tool in flight is named as it runs, and `bash` output streams live instead of arriving all at
|
|
once when the command exits. `ctrl-c` kills a runaway command without ending the turn.
|
|
|
|
**Takes prompts while it works.** Type during a turn and it queues; the queue drains in order
|
|
when the turn ends. `esc` interrupts and clears it. `@` completes workspace paths.
|
|
|
|
**Reads git without touching it.** `git_status`, `git_diff`, `git_log`, `git_show`, and
|
|
`git_blame` are approval-free, because they spawn git with a fixed argument list and cannot
|
|
mutate anything.
|
|
|
|
**Asks instead of guessing.** When a request has two readings that lead to different work,
|
|
the agent puts a question on screen with options.
|
|
|
|
**Delegates searches.** `task` spawns a read-only subagent whose findings come back as one
|
|
message, so a search across forty files does not fill the main context. Its progress
|
|
streams to a panel.
|
|
|
|
**Extensible from the prompt.** `/registry` browses external skills and plugins and installs
|
|
them with one confirmation. A skill is shown in full before its text joins your system prompt;
|
|
a plugin is a manifest of refusal rules, never code.
|
|
|
|
**Remembers between sessions.** Decisions, working commands, and traps go into per-project
|
|
memory that is injected at the start of every future session.
|
|
|
|
**Survives long tasks.** The task list and project memory live outside the message array,
|
|
so they survive both automatic pruning and `/compact`.
|
|
|
|
**Runs headless.** `shiro -p "review this diff" --json` for scripts and CI.
|
|
|
|
**Keeps the tool list affordable.** Fourteen built-in tools, grouped into sets. Each costs
|
|
about 550 characters of schema on every request, so `{ "toolSets": [] }` trims back to the six
|
|
core ones and a disabled set reaches neither the wire nor the prompt.
|
|
|
|
## Documentation
|
|
|
|
Start with whichever question you have. Each guide says what it decided and why, not just what
|
|
the flags are.
|
|
|
|
| Guide | Contents |
|
|
|---|---|
|
|
| [Configuration](docs/configuration.md) | config file, provider presets, environment, every flag |
|
|
| [Tools](docs/tools.md) | every tool, tool sets and what they cost, the approval model |
|
|
| [Agents and thinking](docs/agents.md) | variants, thinking levels, step caps, which to reach for |
|
|
| [Skills](docs/skills.md) | the bundled skills, writing your own, why the catalogue is split |
|
|
| [Plugins](docs/plugins.md) | the interface, the guard and its limits, builtin versus installed |
|
|
| [Registry](docs/registry.md) | installing external skills and plugins, publishing your own |
|
|
| [Memory and state](docs/memory.md) | memory, task lists, sessions, compaction and its repair |
|
|
| [MCP](docs/mcp.md) | connecting servers, namespacing, cost, debugging one |
|
|
| [Headless mode](docs/headless.md) | `-p`, JSON events, exit codes, CI recipes |
|
|
| [Architecture](docs/architecture.md) | how the loop works and why it is built this way |
|
|
| [Development](docs/development.md) | building, testing, adding a tool, releasing |
|
|
| [Roadmap](ROADMAP.md) | what is next and what has been declined |
|
|
| [TODO](TODO.md) | the current work list, with known rough edges |
|
|
|
|
## Commands
|
|
|
|
Type `/` and a menu appears, narrowing as you type.
|
|
|
|
```
|
|
/help /agent [name] /think [level] /provider /models /model <id>
|
|
/skills /plugins /registry [search|add|remove] /init /context
|
|
/todos /notes /memory /tools /compact /cost
|
|
/sessions /resume <id> /save /clear /exit
|
|
```
|
|
|
|
`esc` dismisses a panel, interrupts a running turn, and clears the queue. `ctrl-c` kills the
|
|
running command but keeps the turn. `ctrl-r` expands the reasoning panel. `@` completes a
|
|
workspace path. Up and down recall earlier prompts.
|
|
|
|
## Status
|
|
|
|
Working: the agent loop, tool approvals, subagents, skills, plugins, per-project memory,
|
|
session persistence, MCP, markdown rendering, headless mode, five-platform builds, streaming
|
|
reasoning display, the mid-turn prompt queue, gateable tool sets, read-only git tools, batch
|
|
reads, `@file` completion, interruptible commands, and the external registry.
|
|
|
|
Next up is in [TODO.md](TODO.md); the longer view and what has been declined are in
|
|
[ROADMAP.md](ROADMAP.md). The short version of what is missing: a summary of what compaction
|
|
discarded, `web_fetch`, a spend ceiling, and a cheaper model for subagent searches.
|
|
|
|
## License
|
|
|
|
MIT. See [LICENSE](LICENSE).
|