Tsuki

Tsuki is a fast, tiny, modular coding agent written in Nim.

Warning

Tsuki is in pre-alpha and under active development. Provider and terminal compatibility is claimed only where the manual record has evidence.

Features

• Works in the current directory: lists, searches, and reads files, edits them with a diff preview, and runs shell commands. Writes and commands ask first on an inline approval card; Always allow grants a tool for the session and nothing is ever persisted as a standing permission.
• Packs: every tool, slash command, and prompt fragment comes from a compile-time pack (workspace, edit, shell, skills, web, plan). The core links with zero packs, and each pack can be disabled or tuned from the config file.
• Plans and bootstrap: the model keeps a checklist on screen with update_plan, and /init asks it to write an AGENTS.md for the workspace. Claude models think adaptively with the selected effort.
• MCP servers: a stdio server added in /settings or config.json shows up as a pack, its tools as <name>__<tool> behind the usual approval policy and its prompts as /<name>:<prompt>; /mcp lists and restarts servers.
• Visible cost: the activity line shows elapsed time and the running tool; each turn ends with a footer of duration, tokens in and out, and cost; /usage totals the session, /diff shows what the session changed, @path completes workspace files, and /auto skips the prompts for a session.
• Images: paste a screenshot path or /paste the clipboard image to attach it, and the model can look at workspace images itself with view_image.
• Web access: web_search works with no key through DuckDuckGo and switches to Brave, Tavily, or Exa when a key is stored; web_fetch reads a page as text. Both ask before touching the network and refuse private addresses.
• Providers: OpenAI-compatible endpoints, OpenRouter with catalog discovery, Anthropic Messages with explicit prompt-cache breakpoints, and ChatGPT Codex subscriptions through the Codex App Server.
• Deterministic prompts: the system prompt and tool list are byte-identical across rounds and turns, so provider caches hit; /usage shows the cache hit share.
• Long sessions: type while a turn runs to steer it after the next tool round, /compact summarizes earlier turns, and a repeated identical call is stopped before it loops.
• No config editing: a first run writes the defaults and opens the provider dialog, /settings changes every host and pack setting in place, and custom providers such as Ollama or LM Studio are two fields away.
• Durable sessions saved atomically, resumable after a crash, with chat mode for planning without reading the workspace.

he3

he3 is the terminal UI framework built for Tsuki. It handles terminal setup and restoration, input, Unicode-safe drawing, layouts, widgets, and screen updates. It uses an immediate-mode API backed by retained front and back buffers: the application redraws the desired frame, then he3 diffs it against the previous one.

he3 is fast and lightweight: zero third-party runtime dependencies, no idle polling, and sub-millisecond frame rendering in local release benchmarks.

The long-term goal is for he3 to become a standard TUI framework for the Nim ecosystem. It is its own Nimble package under packages/he3 and its import path is he3.

Quick start

import he3

proc update(event: Event): Update =
  if event.isQuit: quitTui() else: unchanged()

proc draw(frame: var Frame) =
  frame.text("Hello, world!", align = textCenter)

discard runTui(update, draw)

Compile with threads enabled:

nim c -r --threads:on app.nim

Install he3 on its own with the subdir query:

nimble install "https://github.com/nostacks/tsuki?subdir=packages/he3"

Agent views are available from he3/agent. Model and tool workers can post typed events from other threads without coupling he3 to a provider.

Install

Tsuki requires Nim 2.2 or newer. Install the current pre-alpha from GitHub:

nimble install https://github.com/nostacks/tsuki

To build a checkout locally:

nimble build

Start without credentials and add a key in the app:

./build/tsuki --new

Chat or plan with read-only tools only (reads, searches, and web lookups, never writes or commands), or switch with /chat and /agent inside the app:

./build/tsuki --chat

Run one turn without the UI, for scripts and CI. Text goes to stdout, tool lines to stderr, and --json gives one event per line:

./build/tsuki run --approve execute "run the tests and summarise failures"
echo "explain src/tsuki.nim" | ./build/tsuki -p --json

Open the same session in a second terminal and both windows stay in sync; sessions in the same directory see each other with /windows and take short file leases so they cannot clobber each other's edits:

./build/tsuki --session s-1234

Examples

The repository keeps three public examples:

1. hello_world.nim: a minimal he3 application.
2. counter.nim: state, keyboard input, styling, and a testable draw function.
3. agent_chat.nim: the public mock provider and real session/controller/TUI integration.

Compile all examples without running the interactive programs:

nimble examples

Development

nimble test       # product tests, then the he3 debug and release suites
nimble examples   # compile every public example
nimble fuzz       # bounded deterministic property tests
nimble bench      # release benchmarks
nimble docs       # generate API docs under doc/htmldocs
nimble check      # nim check on the executable and the he3 facades
nimble lint       # format, then verify a clean diff and nim check

The same test, fuzz, bench, and docs tasks can be run directly inside packages/he3.

Read the agent guide for configuration, packs, approvals, and caching, the he3 quick start or the full he3 library guide, review the terminal compatibility record, or see the pre-1.0 migration notes.

Platform support

he3 includes POSIX and Windows terminal backends. The compatibility record separates automated checks from manual terminal testing. Platforms without recorded tests are not presented as verified.

License

Tsuki is available under the MIT License.