Muhammad Zakir Ramadhan
5b8503fcd9
Agentic coding CLI on Bun, Ink, and the AI SDK. Core: streamText loop with SDK-level tool approval so a denied call provably never executes; endpoint fallback for OpenAI reasoning models; retry with backoff. Tools: read/write/edit/glob/grep/bash, path-jailed, gitignore-aware, ripgrep with a JS fallback, binary rejection, live bash streaming. Agents: five variants crossing thinking level with tool restriction; plan and review withhold mutating tools from the model. Extensibility: frontmatter skills with on-demand bodies, plugin host with blocking hooks, MCP stdio and HTTP, read-only subagents. State: durable per-project memory, session task lists, session persistence, compaction that repairs provider-item dependencies. Distribution: five-platform cross-compiled binaries with checksums, install scripts, CI on three operating systems. 404 tests, typecheck clean.
4.6 KiB
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.
Built on Bun, Ink, and the AI SDK. Works with Anthropic, OpenAI, and any OpenAI- or Anthropic-compatible endpoint: OpenRouter, Groq, DeepSeek, xAI, Ollama, LM Studio, vLLM.
0.1.0-beta.1 — usable, but the interfaces may still move.
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, 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. read_file refuses binaries rather than filling the
context with mojibake.
Edits with your approval. Every write_file, edit_file, and bash call stops for a
y/a/n decision, with a coloured diff for edits. The guard plugin refuses
irreversible commands outright — rm -rf, git reset --hard, force pushes, DROP TABLE —
and --yolo cannot bypass it.
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.
Documentation
| Guide | Contents |
|---|---|
| Configuration | config file, environment variables, every flag |
| Tools | every tool, 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 or interrupts a running turn. 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.
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: streaming reasoning display,
a message queue for prompts typed mid-turn, @file completion, and git-aware tools.
License
MIT. See LICENSE.