kissa 0.1.0

A quiet listening room for your thinking sessions with Claude

kissa

A jazz-kissa for thinking sessions — a TUI for managing Claude Code thinking conversations. It drives the friction between "a fleeting idea" and "a searchable note" down to zero.

Install

uv tool install kissa     # or: pipx install kissa
# not on PyPI yet? install from git:
uv tool install git+https://github.com/yiochou/kissa

Prerequisites: a logged-in Claude Code (credentials in ~/.claude are shared) or an ANTHROPIC_API_KEY in the environment. No Node.js needed — the SDK bundles the claude binary (which is why the install weighs in around 250 MB).

Run

kissa                     # open the TUI
kissa "some topic"        # quick capture: start a session directly
kissa --debug             # write debug logs to the log directory

Keybindings

Key	Action
n	New session (enter a topic → auto-sends the opening prompt)
b	Branch the current session (fork, inherits full history)
e	End (confirm, then sends the end instruction; approve the draft in the chat pane)
x	Archive (guarded by end status and completion-signal tier)
q	Quit (sessions persist and resume on next launch; see limitations below)

Completion Signal Protocol

Want to plug in your own instructions (e.g. a personal slash command)? Have it emit this on its own line once the note is saved:

[kissa:saved <absolute path to the note file>]

kissa uses this to confirm the note was saved (archiving proceeds directly and shows the path). It also works without it — archiving then falls back to a plain confirmation dialog. See the design doc for the full contract.

Note: the marker must be emitted within a single message, and the path must not contain ] — the marker is parsed per-message with a line-anchored regex.

Configuration

• Profiles: profiles.yaml in the config directory (location is OS-dependent; override with KISSA_CONFIG_DIR)
• State: state.json in the data directory (override with KISSA_STATE_DIR)
• Default notes location: ~/Documents/kissa (change the instruction text in profiles.yaml)

Known Limitations

• Chat transcripts are display-only and not persisted: after a restart the chat pane starts empty, though the underlying session still resumes with full context (planned for V2).
• A dead session id isn't auto-flagged as stale; it only surfaces as an error on the next turn (you can archive it directly).
• The n/b/e/x/q keys only work when the input box isn't focused (Tab switches focus).

Development

uv run pytest                          # unit + Pilot tests (no real SDK calls)
uv run ruff check . && uv run mypy src # lint + type check
uv run python scripts/smoke_sdk.py     # manual SDK integration check

License

MIT