Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Channels & Threads

Kimaki's whole design rests on one mapping: a Discord channel is a project, and a thread is a coding session. Understanding this makes everything else obvious.
  Discord                       Your machine
  ┌─────────────────┐           ┌─────────────┐
  │ server          │           │             │
  │  #web-app       │  ───────▶ │ /code/web   │
  │   ├─ login      │  ───────▶ │ session A   │
  │   └─ dark       │  ───────▶ │ session B   │
  │  #api           │  ───────▶ │ /code/api   │
  │   └─ limit      │  ───────▶ │ session C   │
  └─────────────────┘           └─────────────┘

Why this matters

Most chat-based agent tools put everything in one channel, like an iMessage thread. Sessions stack on top of each other, context bleeds between unrelated tasks, and there is no clean way to find or resume a specific piece of work.
Kimaki partitions work along the two axes that actually matter:
  • Projects → channels. Switch the project you're working on by switching channels.
  • Sessions → threads. Switch the task you're working on by switching threads.
Each thread keeps its own conversation, its own session state, and its own history. You can leave a thread, come back days later, and continue where you left off.
Treat threads like git branches for conversations. One thread per task keeps each session focused and easy to search later.

How a channel becomes a project

Add a project from the CLI. Kimaki creates a text channel for the directory and stores the link in its local database (~/.kimaki/kimaki.db):
# Add the current directory as a project channel
kimaki project add

# Add a specific directory
kimaki project add /code/web-app

# See every project and its channel
kimaki project list
New channels go into a category named Kimaki <machine>, one per machine. On first start Kimaki creates a general channel (usually #kimaki) and an onboarding thread where the agent helps you find and add your projects. See Managing Projects for details.

How a message becomes a session

The first message you send in a project channel creates a thread and starts an OpenCode session in that channel's directory. The thread name is your message (up to 80 characters). The agent replies inside the thread:
-# *using anthropic/claude-sonnet-4-5 ⋅ build*
Looking at the login test first.
-# ┣ shell _run the login tests_
-# ◼︎ edit *login.test.ts* (+4-2)
The test raced the session cookie. It awaits it now.
-# *web-app ⋅ main ⋅ 2m 30s ⋅ 41% ⋅ claude-sonnet-4-5*
From then on, messages in that thread continue the same session. Messages in the channel (outside any thread) start new threads and new sessions. This is what keeps tasks isolated.
  #web-app channel
       │
       │ first message ──▶ creates "fix login" ──▶ session starts
       │
       │ another msg ────▶ creates "dark mode" ──▶ separate session
       │
       └─ thread "fix login" ──▶ continues the same session

Resuming, forking, and searching

Because every session is a thread, you get Discord's organization for free:
  • Resume any session of the project with /resume (autocomplete lists them, including sessions started in the OpenCode TUI). The session moves to a new thread.
  • Fork from an earlier message with /fork, or fork the whole context into a side thread with /btw.
  • Search with Discord's search, or with rg <query> ~/.kimaki/transcripts from the terminal (see Sessions).
See Managing Sessions for every session command.

One bot per machine, many channels

A Kimaki bot runs on one machine and answers only in the channels mapped in its own database. To control more machines, run Kimaki on each one; each machine gets its own Kimaki <machine> category in the same server. The same project on two machines gets two channels, the second one with a -<machine> suffix. See Advanced Setup for multi-machine layouts.