Initial commit: shiro-neko 0.1.0-beta.1

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.
2026-09-02 17:30:18 +07:00
commit 5b8503fcd9
93 changed files with 12775 additions and 0 deletions
@@ -0,0 +1,140 @@
+# Configuration
+
+Settings come from three places. Later wins:
+
+1. `~/.shiro-neko/config.json`
+2. environment variables
+3. command-line flags
+
+## The config file
+
+Written by `/provider`, editable by hand. Every field is optional.
+
+```json
+{
+  "provider": "openai",
+  "model": "gpt-5",
+  "baseURL": "https://api.openai.com/v1",
+  "apiKey": "sk-...",
+  "presetId": "openai",
+  "agent": "default",
+  "thinking": "medium",
+  "maxRetries": 3,
+  "plugins": ["guard", "time"],
+  "mcpServers": {
+    "fs": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
+  }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `provider` | wire protocol: `anthropic` or `openai`. Not the vendor — Groq, OpenRouter, and Ollama all speak `openai` |
+| `model` | model id as the endpoint names it |
+| `baseURL` | API root. Defaults to the official endpoint for the provider |
+| `apiKey` | sent as `Authorization: Bearer` for `openai`, `x-api-key` for `anthropic` |
+| `presetId` | which preset `/provider` chose, so it can show what is configured |
+| `agent` | default variant: `default`, `quick`, `deep`, `plan`, `review` |
+| `thinking` | default level: `off`, `low`, `medium`, `high`, `max` |
+| `maxRetries` | retries per model call for transient failures. Default 3 |
+| `plugins` | which plugins to enable. Omit for `["guard", "time"]` |
+| `mcpServers` | see [MCP](mcp.md) |
+
+## Provider presets
+
+`/provider` offers these. Each sets `baseURL` and the wire protocol for you.
+
+| Preset | Protocol | Endpoint |
+|---|---|---|
+| Anthropic | `anthropic` | `api.anthropic.com/v1` |
+| OpenAI | `openai` | `api.openai.com/v1` |
+| OpenRouter | `openai` | `openrouter.ai/api/v1` |
+| Groq | `openai` | `api.groq.com/openai/v1` |
+| DeepSeek | `openai` | `api.deepseek.com/v1` |
+| xAI | `openai` | `api.x.ai/v1` |
+| Ollama | `openai` | `localhost:11434/v1` |
+| LM Studio | `openai` | `localhost:1234/v1` |
+| Custom OpenAI-compatible | `openai` | you supply it |
+| Custom Anthropic-compatible | `anthropic` | you supply it |
+
+After the key is entered, `GET /v1/models` is called and the list becomes a picker. If the
+endpoint does not implement it, you type the model id instead — the setup still completes.
+
+## Environment variables
+
+| Variable | Effect |
+|---|---|
+| `SHIRO_PROVIDER` | overrides `provider` |
+| `SHIRO_MODEL` | overrides `model` |
+| `SHIRO_BASE_URL` | overrides `baseURL` |
+| `SHIRO_API_KEY` | overrides `apiKey` |
+| `ANTHROPIC_API_KEY` | used when `provider` is `anthropic` and no key is set |
+| `OPENAI_API_KEY` | used when `provider` is `openai` and no key is set |
+| `SHIRO_HOME` | relocates config, sessions, memory, history, and user skills |
+| `SHIRO_INSTALL_DIR` | where `install:local` and the installers put the binary |
+| `SHIRO_REPO` | which GitHub repo the installers download from |
+| `SHIRO_VERSION` | pins the version the installers fetch |
+
+`SHIRO_HOME` is what the test suite uses to keep a run out of your real config.
+
+## Flags
+
+```
+shiro [options]
+shiro -p "prompt"          headless, prints to stdout
+cat file | shiro -p        prompt read from stdin
+```
+
+| Flag | Effect |
+|---|---|
+| `-p`, `--print [prompt]` | headless mode. Needs `--yolo` for tool use |
+| `--json` | with `-p`, one JSON event per line |
+| `-c`, `--continue` | resume the newest session for this directory |
+| `-r`, `--resume <id>` | resume by session id or unique prefix |
+| `--agent <name>` | `default`, `quick`, `deep`, `plan`, `review` |
+| `--think <level>` | `off`, `low`, `medium`, `high`, `max` |
+| `--provider <name>` | `anthropic` or `openai` |
+| `--model <id>` | model id |
+| `--base-url <url>` | API root |
+| `--no-mcp` | skip MCP servers |
+| `--no-subagent` | omit the `task` tool |
+| `--no-instructions` | ignore `AGENTS.md` and friends |
+| `--no-skills` | ignore builtin and project skills |
+| `--no-plugins` | disable all plugins, including the guard |
+| `--no-memory` | do not load or write project memory |
+| `--yolo` | skip every approval prompt |
+| `-v`, `--version` | version, bun version, platform, source or compiled |
+| `-h`, `--help` | usage |
+
+## Where things live
+
+```
+~/.shiro-neko/
+  config.json                 provider, model, key, defaults
+  sessions/<uuid>.json        transcripts, token counts, cost, task list
+  memory/<hash>.json          durable per-project notes
+  history/<hash>.json         prompt history for up-arrow recall
+  skills/*.md                 your own skills
+```
+
+Project files:
+
+```
+<project>/
+  AGENTS.md                   instructions injected into the system prompt
+  .shiro/skills/*.md          project skills, override user and builtin
+  .shiroignore                extra ignore rules on top of .gitignore
+```
+
+Memory and history file names are SHA-256 prefixes of the absolute project path, because a
+path is not a safe filename.
+
+## OpenAI reasoning models
+
+Newer OpenAI models reject function tools on `/v1/chat/completions` and require
+`/v1/responses`. For `api.openai.com` both are chained: a 400, 404, 405, 415, 422, or 501
+on the first switches to the second, sticks for the rest of the session, and prints one
+notice. Retryable failures — 429 and 5xx — are left to the SDK's backoff instead.
+
+Third-party endpoints get a plain chat-completions model with no fallback probe, since they
+do not implement `/v1/responses`.