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

Debug sessions and report bugs

Export the session events, put the evidence in a secret gist, then open a GitHub issue. Do not open a pull request.
Agents must read this page first before filing anything on remorses/kimaki.
  /session-id
       │
       v
  kimaki session events ──> jq ──> ground truth (events, not guesses)
       │
       v
  kimaki.log + prompts + model id
       │
       v
  secret gist ──> events jsonl + log + session markdown
       │
       v
  gh issue create (body links gist)
       │
       v
  wait for remorses ──> PR only if he agrees in a comment

Collect ground truth

Do not describe what you think happened. Quote what the files show.
  1. Get the session id with /session-id in the Discord thread, or kimaki session list. A Discord thread ID or thread URL also works in the commands below.
  2. Export the recorded events. They are the source of truth for display bugs (footer after abort, stuck typing, missing tool lines).
  3. Copy kimaki.log. It resets on every bot start, so copy it before you restart.
  4. Record the model id and the verbatim user prompts. Do not paraphrase.
kimaki session events ses_xxx > ./tmp/ses_xxx.jsonl
kimaki session read ses_xxx > ./tmp/ses_xxx.md
kimaki session read ses_xxx --thinking --verbose > ./tmp/ses_xxx-full.md
cp "$(kimaki logs)" ./tmp/kimaki.log
kimaki status
npm ls -g kimaki
kimaki logs prints the log path: ~/.kimaki/kimaki.log by default, or <dataDir>/kimaki.log if you pass --data-dir. kimaki status shows the OpenCode URL and version. npm ls -g kimaki shows the Kimaki version.
Kimaki records events only for sessions that have a Discord thread, in <dataDir>/session-events/<threadId>.jsonl. One file holds the root session, its subagents and Kimaki internal events. Streaming deltas are skipped, very long strings are cut, and a file starts again when it passes 20 MB. For sessions without a thread (for example your own OpenCode TUI sessions), use kimaki session read.

Model id and prompts

kimaki session read includes the exact providerID/modelID on each assistant message and the verbatim user prompts. Copy both from ./tmp/ses_xxx.md; do not rely on memory.
Before upload, remove secrets such as tokens, API keys, cookies, and unrelated private prompts. Keep event order, timestamps, model ids, and relevant error lines unchanged.

Inspect the events

Each line is { "at": <ms>, "event": <OpenCode event> }. Read the file before you write the issue.
# event type counts
jq -r .event.type ./tmp/ses_xxx.jsonl | sort | uniq -c

# run lifecycle only
jq -r 'select(.event.type | startswith("session.execution.")) | [.event.created, .event.type, .event.data.sessionID] | @tsv' ./tmp/ses_xxx.jsonl

# timestamps and types
jq -r '[.event.created, .event.type] | @tsv' ./tmp/ses_xxx.jsonl

# retries
jq 'select(.event.type == "session.retry.scheduled")' ./tmp/ses_xxx.jsonl
If the file does not contain the event you expected, say that. Do not invent a cause.

Open an issue, never a PR

File issues on github.com/remorses/kimaki/issues.
Never open a pull request. If you have a fix or a reproduction, put it on the issue. A PR is allowed only after remorses agrees in a comment on that issue.

Share evidence in a gist

Put the events jsonl, log, session markdown, and reproduction code in one secret gist. Paste the URL printed by gh gist create into the issue body.
A secret gist is unlisted, not private. Anyone with its URL can read it. Remove secrets and unrelated private data before upload. If the evidence cannot be public, do not upload it; state that private evidence is available to the maintainer.
# gists are secret by default; omit the reproduction file if you do not have one
gh gist create --desc "kimaki ses_xxx debug" \
  ./tmp/ses_xxx.jsonl \
  ./tmp/ses_xxx.md \
  ./tmp/kimaki.log \
  ./tmp/reproduction.ts

# paste the returned gist URL into ./tmp/kimaki-issue.md, then create the issue
gh issue create -R remorses/kimaki \
  --title "Footer appears after abort in ses_xxx" \
  --body-file ./tmp/kimaki-issue.md

Issue body

Keep it short. Use facts from the events file and the log.
**Session:** ses_xxx
**Model:** anthropic/claude-opus-4-6
**Kimaki version:** output of `npm ls -g kimaki`
**OpenCode version:** from `kimaki status`
**OS:** macOS 15.2
**Gist:** https://gist.github.com/...

**Steps to reproduce:**
1. ...
2. ...

**User prompts** (verbatim, in order):
1. ...
2. ...

**What the files show:**
- events line N: `session.execution.started` at <created>
- events line M: `session.execution.interrupted`, then a footer message was posted
- log: <exact error line>

**What I expected:**
No footer after abort.
Do not write "probably a race" or "might be Discord". If you do not have an event or a log line, say unknown.

Reproduce with a test

Only if you have the Kimaki repo. A recorded events file is a test fixture: the Kimaki reducer is a pure function of the events, so replaying the file shows the same Discord output.
  1. Copy the file into docs/opencode-v2-events/.
  2. Add a test in kimaki/src/thread-reducer.fixtures.test.ts that calls replay({ events: loadFixture('ses_xxx.events.jsonl') }) and snapshots the effects.
kimaki session events ses_xxx > docs/opencode-v2-events/ses_xxx.events.jsonl
cd kimaki && pnpm run test --run src/thread-reducer.fixtures.test.ts
A file without a session.created event needs an explicit initial view in replay().
Put the failing test on the issue (gist or snippet). Do not open a PR unless remorses asked for one.