takopi/docs/reference/index.md

Reference

Reference docs are authoritative and exact. Use these when you need stable facts, schemas, and contracts.

If you’re trying to achieve a goal (“enable topics”, “fetch a file”), use How-to.
If you’re trying to understand the why, use Explanation.

Most-used reference pages

• Commands & directives
  • Message prefixes like /<engine-id>, /<project-alias>, and @branch
  • In-chat commands like /cancel, /new, /ctx, /file …, /topic …
• Configuration
  • takopi.toml options and defaults
  • Telegram transport options (sessions, topics, files, voice transcription)

Normative behavior

• Specification
  The normative (“MUST/SHOULD/MAY”) contract for:
  • resume tokens + resume lines
  • event model
  • progress/final message semantics
  • per-thread serialization rules

Plugins and extension contracts

• Plugin API
  The only supported import surface for plugins: takopi.api
• Context resolution
  How Takopi resolves project + worktree context from directives, replies, and chat ids.

Transport reference

• Telegram transport
  Rate limits, outbox behavior, retries, message editing rules.

Runner reference

These are “engine adapter” implementation details: JSONL formats, mapping rules, and emitted events.

• Runners overview
• Claude:
  • runner.md
  • stream-json-cheatsheet.md
  • takopi-events.md
• Codex:
  • exec-json-cheatsheet.md
  • takopi-events.md
• OpenCode:
  • runner.md
  • stream-json-cheatsheet.md
  • takopi-events.md
• Pi:
  • runner.md
  • stream-json-cheatsheet.md
  • takopi-events.md

For LLM agents

If you’re an LLM agent contributing to Takopi, start here:

• Agent entrypoint
• Repo map
• Invariants (runner contract, resume handling, “don’t break this” rules)