Muhammad Zakir Ramadhan
2fa6ee247b
Tools, six built-in to fourteen: - read_many_files: up to 20 paths read concurrently, each with its own window. An unreadable path is reported in its own block instead of throwing. - multi_edit: several edits to one file, validated in memory first so a late failure cannot leave the file half-written. - list_dir: ignore-aware depth-limited tree. - git_status/diff/log/show/blame: read-only, spawned with a fixed argv rather than a shell string, which is what makes them safe to auto-approve. toolSets gates them. core is always on; edit-plus and git are optional. A disabled set reaches neither the wire nor the system prompt, since a prompt naming an absent tool teaches calls that cannot succeed. Interface: - Reasoning streams to a collapsed panel, ctrl-r expands, dropped when the turn ends: it is progress, not the answer. - The tool in flight is named from tool-input-start, before its arguments finish streaming, and cleared on its result. - Prompts typed mid-turn queue and drain in order. esc clears the queue as well as aborting. - @ opens a path picker fed by the ignore-aware walker. Prefix matches rank above substring matches, so @src/ means "under src/". The walk runs on the first @, not at startup. ctrl-c kills the command in flight and keeps the turn. The call throws rather than returning, so the model cannot read a killed command as one that ran and failed on its own terms. The kill takes the whole process tree: killing cmd /c alone left the real command holding both pipes open, so the read never returned and the interrupt did nothing for 19 seconds. Two pruning fixes: - A tool result whose tool call was pruned is now dropped with it. Pruning counts messages, so the cut landed between an assistant tool-call and the tool message answering it, producing 400 "No tool call found for function call output with call_id ...". The reverse pairing is left alone: a call awaiting its result is what a suspended approval looks like. - ignore.ts called statFs without importing it, so walk() crashed on the first symlink. 482 tests, up from 404. Docs synced across README, ROADMAP, TODO, and all of docs/: tool sets, the new tools, ctrl-c semantics, the tool-start event, and the two hand-maintained tool-name lists recorded as a known weakness.
Shiro Neko
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.
Install
A single prebuilt binary. No runtime, no node_modules.
# 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:
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
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.1 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.
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
| Guide | Contents |
|---|---|
| Configuration | config file, environment variables, every flag |
| Tools | every tool, tool sets, the approval model, the guard |
| Agents and thinking | variants, thinking levels, read-only modes |
| Skills | the bundled skills and writing your own |
| Plugins | the plugin interface and the builtins |
| Memory and state | memory, task lists, sessions, compaction |
| MCP | connecting Model Context Protocol servers |
| Headless mode | -p, JSON events, exit codes, CI recipes |
| Architecture | how the loop works and why it is built this way |
| Development | building, testing, releasing |
| Roadmap | what is next and what has been declined |
| TODO | the current work list |
Commands
Type / and a menu appears, narrowing as you type.
/help /agent [name] /think [level] /provider /models /model <id>
/skills /plugins /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, and interruptible commands.
Next up is in TODO.md; the longer view and what has been declined are in
ROADMAP.md. The short version of what is missing: a summary of what compaction
discarded, web_fetch, and a cheaper model for subagent searches.
License
MIT. See LICENSE.