Rocky 发布本地优先 AI 工程助手，支持审批门与变更回滚

A local-first AI engineering partner for one person and one computer.

Rocky chats with you, works in your project folders, reads and writes Office documents, and hands larger coding tasks to an external coding agent. Every change it makes goes through one approval gate and can be undone.

English · 繁體中文

Features · Quick start · How it works · Security · Development · Decisions

Features

• Works in your project. Search, read, edit files and run commands inside the folder you choose, then run your tests to check the result. Rocky follows the project's AGENTS.md.
• Approvals that stay out of your way. Two modes. Ask when needed (the default) asks for dangerous commands, secrets, protected files and actions outside the project; hands off asks only before reading a secret. "Allow for this conversation" covers that kind of action; "always allow" saves a command rule you can see and remove in Settings. Deny rules hold in both modes. An approval is bound to a hash of the exact content it showed.
• Undo for every change. Files are snapshotted before each write; each turn ends with a card listing what changed and a Restore all button. Every action leaves a receipt.
• Plan mode. Turn on Plan next to the input box: Rocky only reads, then proposes 1–3 options. Choosing one turns plan mode off and the work starts.
• Documents as first-class files. PDF, Word, Excel, PowerPoint, Markdown and HTML are read as Markdown and created from Markdown; Word, Excel and PowerPoint are edited in place, keeping their formatting. Chinese text round-trips intact. A side panel previews the layout before and after a change.
• Delegation to OpenCode. Ask Rocky to hand off a coding task. It runs in the background in its own Git worktree; you approve its actions in Rocky; Rocky checks the diff and reruns the tests before you apply or discard the result.
• Extensible. Long-term memory in Markdown files, skills (SKILL.md folders) and MCP servers (stdio or HTTP), each tool with its own approval setting.
• Bilingual interface. Traditional Chinese (default) and English, with Roko the mascot showing what Rocky is doing.

Quick start

Requirements

• Node.js 24 and Git
• A model: any OpenAI-compatible endpoint, OpenAI, or a local Ollama
• Optional: OpenCode for delegation (npm install -g opencode-ai)

No C/C++ compiler, Python or Microsoft Office is needed.

Install and start

git clone https://github.com/Suckashi/Rocky.git
cd Rocky
npm ci
npm start

Rocky prints a one-time login link and opens it in your browser.

On Windows you can instead run the launcher, which installs the pinned dependencies on first run (npm ci), starts Rocky, and reopens the browser if Rocky is already running:

powershell -ExecutionPolicy Bypass -File .\Start-Rocky.ps1

Rocky is verified on Linux and Windows; macOS is untested.

First run

1. Choose a model: base URL, model name and API key. The key is stored only on your computer.
2. Choose a project folder: Rocky reads, edits and runs commands only there.
3. Start chatting. When Rocky needs you, the approval panel replaces the input box: press 1–4 to choose, Enter to confirm, Esc to reject.

Configuration

Settings are made in the app. A few environment variables cover the rest:

The data folder holds conversations, receipts and snapshots (rocky.sqlite, snapshots/), memory (memory/), skills (skills/), job worktrees (worktrees/) and secrets.json (model key and MCP settings). It is never inside a Git checkout.

How it works

Browser (React, zh-TW / en)
   │  HTTP + SSE on 127.0.0.1, every request authenticated
   ▼
Rocky (one Node.js process)
 ├─ Agent        Deep Agents + LangChain, OpenAI-compatible models
 ├─ Action gate  policy → approval → single-use pass → execute → receipt
 ├─ Snapshots    content-addressed copies of every file before it changes
 ├─ Jobs         OpenCode over ACP, one Git worktree per job, queued
 ├─ MCP client   your stdio / HTTP servers
 ├─ Documents    pure Node libraries for pdf, docx, xlsx, pptx, md, html
 └─ Storage      node:sqlite + files in the data folder

Every tool call passes the action gate before it runs, including calls from OpenCode, MCP and the Restore button. The functions that write files or run commands accept only a single-use pass issued by the gate for that exact content, so nothing can skip the gate. Commands run as argument lists, never through a shell. An action whose outcome is unknown is never retried automatically.

The reasoning behind each design choice is recorded in the architecture decision records.

Security and privacy

• Rocky listens on 127.0.0.1 only. Do not expose it to a network.
• No telemetry. Third-party install and runtime telemetry is switched off.
• Rocky's own outbound requests go only to the model endpoints and MCP servers you configure. OpenCode, when you use it, also contacts the npm registry at startup and may download ripgrep.
• Rocky's access token never leaves its process: the browser signs in with a one-time code. The model API key is never shown in the interface; OpenCode receives it to call the model.
• Rocky has no operating-system sandbox: approved commands run with your user's permissions. Read what you approve.

To report a vulnerability, see SECURITY.md.

Development

npm ci
npm run check        # type check, lint, formatting, i18n, unit and integration tests
npm run test:e2e     # browser end-to-end tests against a scripted model
npm run test:e2e:jobs  # the same for delegation (needs OpenCode)
npm run eval         # 31 real tasks against a live model, compared with evals/baseline.json

The end-to-end tests use the system Edge, or the browser set in ROCKY_E2E_BROWSER. Run npm run eval after changing prompts, tools or the agent loop; models vary between runs, so use --repeat 3 before treating a drop as real.

GitHub Actions runs npm run check and the build on Windows and Ubuntu for pull requests to main (a few minutes; it does not block merging). The browser tests, delegation tests and the evaluation run locally. On Windows, scripts/verify-windows.ps1 runs the install, all checks, both browser tests and the launcher in one go and writes a summary to verify-results\.

Project layout:

src/server/   Node.js server: agent, action gate, jobs, documents, MCP, storage
src/web/      React interface and i18n catalogs (zh-TW, en)
tests/        unit and integration tests (Vitest)
scripts/      browser end-to-end tests, i18n check, Windows verification
evals/        evaluation tasks and baseline
docs/adr/     architecture decision records

Project status

Rocky V1 is feature-complete. It is verified on Linux, and on Windows with scripts/verify-windows.ps1; macOS is untested. There is no packaged release yet. Known limitations include:

• No operating-system sandbox; commands run with your permissions.
• Only OpenCode is supported for delegation.
• Layout previews are drawn by Rocky and can differ from how Office shows the file.
• Scanned (image-only) PDFs cannot be read.

Contributing

Rocky is maintained by its owner for personal use. Before changing code, read AGENTS.md: every user-facing string goes through the i18n catalogs, checks must be reported honestly, and a change of approach gets a short ADR.

License

Rocky's source code is licensed under the Apache License 2.0. The Roko mascot artwork in assets/roko/ is not covered by that license; see NOTICE and assets/roko/README.md. Third-party attributions are listed in THIRD_PARTY_NOTICES.md.