tinycode 发布本地优先 AI 编码助手，单个 Go 二进制无运行时依赖

Local-first AI coding assistant. Bring any model — single binary, no runtime dependencies.

Local-first, model-agnostic AI coding assistant. A single Go binary embeds the HTTP server, terminal UI, session management, LLM client, and tool execution --- no Node.js, no separate server process. Works with any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, OpenRouter, and more). Your sessions stay in local SQLite; data leaves your machine only when you send a prompt to a provider you configured.

Quick start

Install

# One-liner (macOS / Linux) — installs to ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/bobbyjohnstx/tinycode/main/install.sh | sh

# Or Homebrew
brew install bobbyjohnstx/tap/tinycode

See docs/install.md for platform notes, PATH setup, and verifying the install.

First prompt

Have a local model running (for example ollama serve and ollama pull qwen3.5:9b), then:

tinycode doctor                   # diagnose config/providers (not a setup wizard)
tinycode                          # TUI in the current directory
tinycode /path/to/project         # TUI against a project

If no model was auto-discovered, type /connect in the TUI to pick a provider and model. There is no separate tinycode setup command — doctor + /connect is the first-run path.

Type a prompt and press Enter:

Explain what this repository does in 2 sentences.

Press Ctrl+X then m to pick a model if needed. Full walkthrough: docs/quickstart.md.

Ctrl+P opens the command palette. Ctrl+X opens the which-key panel for leader shortcuts.

Build from source

git clone https://github.com/bobbyjohnstx/tinycode.git && cd tinycode
make build
./dist/tinycode

Requires Go 1.27.1+. Other modes: tinycode web (browser UI), tinycode serve (headless API), tinycode acp (IDE), tinycode run (non-interactive).

What it is

Key features

• Multi-agent orchestration --- build agent delegates to executor, architect, and critic subagents; /swarm dispatches parallel subagents as goroutines (not the legacy TypeScript tmux swarm — see docs/spec/16-not-implemented.md); --plan flag shows decomposition for review before dispatch
• 14 built-in agents --- architect, debugger, executor, code-reviewer, and more (Tab to cycle, /ask for one-shot); plan is a native mode (plan_enter/plan_exit) for read-only research and planning
• 10 bundled skills --- debug, verify, trace, review, plan, test, doctor, mcp-setup, remember, deepinit
• Workflow commands --- /effort adjusts reasoning depth per session, /goal runs autonomous multi-turn loops until a condition is met, /branch forks conversations to try alternatives
• Context management --- /context visualizes context window usage with per-category breakdown, /btw asks side questions without polluting history, /changes shows only files tinycode modified (not all uncommitted changes); automatic elision at 80% context, LLM summarization at the limit, /compact for manual compaction
• Built-in tools --- monitor watches background processes with buffered event delivery, notepad provides session-scoped scratch storage that survives compaction, report_findings outputs structured code review results, notify sends desktop notifications with urgency levels
• Hooks --- shell hooks in settings.json for lightweight lifecycle automation without writing a plugin; additionalContext lets hooks inject text into the model's context
• Frecency ranking --- command palette ranked by usage frequency + recency
• MCP integration --- connect external tool servers via stdio, SSE, or streamable HTTP; manage with /mcp dialog
• Multimodal input --- paste images from clipboard (/paste-image) for vision-capable models
• Extended thinking --- /thinking controls reasoning budget (off/low/medium/high/max)
• Model scoping --- /scoped-models favorites list to filter the model selector
• Snapshot undo/redo --- /undo and /redo revert or restore AI file changes; /rewind rolls back to any earlier conversation turn
• Diff viewer --- /diff shows uncommitted changes inline
• Clipboard copy --- /copy copies responses to clipboard with code-block picker
• apply_patch tool --- atomic multi-file edits via unified diff
• @ file references --- autocomplete with directory drill-down
• Session auto-titling --- titles generated from the first prompt
• In-transcript search --- Ctrl+F to search the chat, Ctrl+N/Ctrl+P to navigate matches
• Session archive --- /archive soft-deletes sessions (recoverable)
• HTML export --- /export html for self-contained HTML with syntax highlighting
• Which-key panel --- press Ctrl+X to see all leader key follow-ups in a floating overlay
• Terminal bell and desktop notifications --- audible bell on task completion; notify tool for desktop alerts with WSL support
• Leader key system --- Ctrl+X prefix for sidebar, sessions, editor, diff, themes, MCP, and more
• Session resume from CLI --- -c continues the most recent session; -r resumes by ID or title
• tinycode doctor --- headless diagnostics that verify config, database, providers, agents, and plugins; detects VS Code, Cursor, Neovim, and JetBrains and prints ACP setup hints
• Safe mode --- --safe-mode skips plugins, MCP, and user agents; status bar shows bold indicator
• System prompt override --- --append-system-prompt and --append-system-prompt-file inject custom instructions
• Token budget ceiling --- --max-tokens sets a cumulative token limit; session aborts when exceeded
• External editor --- /editor opens $EDITOR; /editor @file edits a file directly
• Interactive shell --- /shell drops into a shell session

Interfaces

The primary interface is the terminal UI (TUI) --- a full-featured interactive session with conversation history, model switching, agent/skill invocation, and inline tool approval. The TUI starts instantly and keeps you in the same environment as your code.

tinycode also supports:

• Web UI (tinycode web) --- serves the embedded SolidJS SPA plus API and opens a browser with an auth URL. This is the supported GUI path for the Go product. In-browser PTY and session share/publish are not available (config.share defaults to "disabled").
• Headless API server (tinycode serve) --- REST + SSE endpoints only (no SPA); for programmatic access
• Agent Client Protocol (tinycode acp) --- real stdio ACP transport for IDE integration (internal/acp/service.go, …; VS Code, Zed, JetBrains)
• Non-interactive mode (tinycode run) --- run a prompt and exit, for scripts and CI

There is no desktop shell in this repository. The GUI is tinycode web.

Architecture

Standard Go layout: cmd/ for binaries, internal/ for private packages, pkg/ for public SDK.

cmd/tinycode/ --- Main binary

Single entry point. Subcommands: tui (default), serve, web, acp, run, models, providers, session, status, export, plugin, mcp, init, agent, doctor, debug, version.

internal/ --- Core packages

pkg/plugin/ --- Public Go plugin SDK

Protocol definitions, hook interfaces, and tool registration for building plugins.

Plugins

30 built-in plugins, each a standalone Go binary communicating over JSON-RPC via stdin/stdout.

Red Hat --- OpenShift

Red Hat --- Ansible

Red Hat --- RHOAI

Red Hat --- Platform

Plugins use the SDK in pkg/plugin/. See docs/plugin-development.md for building custom plugins.

Agents

Press Tab to cycle through agents, or use <leader>a to pick from a list. Use /ask <agent> <prompt> to invoke any agent as a one-shot subagent.

Built-in agents

Agents with a .compact.md variant automatically use a smaller prompt for models with limited context windows.

Configuration

Config is loaded from ~/.config/tinycode/ with a 3-name fallback per directory: tinycode.jsonc → tinycode.json → config.json (first file found wins; JSONC comments are supported). Project config uses the same names under .tinycode/ (or walking up from the working directory); innermost wins.

Provider auto-discovery

tinycode probes local LLM providers at startup:

Environment variables

Why Go

tinycode was rewritten from TypeScript/Bun to Go. The single-binary, no-runtime architecture unlocks capabilities that weren't practical in the original:

Native concurrency for multi-agent work

Go's goroutines make subagent orchestration trivial. Commands like /swarm spawn parallel agents as lightweight goroutines (~4KB each) sharing the same process, tools, and event bus. No child processes, no tmux panes, no IPC serialization.

The TypeScript version required tmux to run multiple agents — each needed its own Node.js process with a separate event loop. Sharing state meant pipes, temp files, or socket IPC. In Go, a subagent is:

go func() {
    result := processor.Process(ctx, prompt)
    // result is immediately available in shared memory
}()

Context cancellation propagates automatically — cancel the parent, and every child goroutine winds down cleanly via ctx.Done(). No signal forwarding across process boundaries.

Single binary, zero dependencies

go build produces one static binary. No Node.js runtime, no node_modules, no package manager. The web UI is embedded via go:embed. SQLite is pure Go (modernc.org/sqlite), so no C toolchain or CGO needed. Cross-compilation to linux/arm64 works out of the box.

Resource efficiency

A typical session uses ~20MB RSS. The TypeScript version needed ~150MB (Node.js runtime + V8 heap). Goroutine-based concurrency means 50 parallel subagents add negligible memory overhead, while 50 Node.js child processes would consume gigabytes.

Building

make build          # Build for current platform -> dist/tinycode
make build-all      # Cross-compile for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64
make package        # Create release archives for all platforms
make test           # Run all tests
make test-race      # Run all tests with -race
make lint           # go vet + staticcheck
make check          # lint + tests
make embed-webapp   # Embed SolidJS web app into the binary (builds from packages/app)
make clean          # Remove build artifacts

The runtime is Go only. packages/ is legacy TypeScript kept so make embed-webapp can build the web UI (app, sdk, ui, tinycode, and plugin). See docs/building.md and docs/spec/README.md.

Documentation

• Install: docs/install.md
• First session: docs/quickstart.md
• CI / GitHub Actions: docs/ci-integration.md
• Spec index: docs/spec/README.md
• Architecture: docs/architecture.md
• Build & embed web UI: docs/building.md
• TypeScript features not in Go: docs/spec/16-not-implemented.md

License

MIT