Metadata-Version: 2.4
Name: kissa
Version: 0.1.0
Summary: A quiet listening room for your thinking sessions with Claude
Project-URL: Homepage, https://github.com/yiochou/kissa
Project-URL: Repository, https://github.com/yiochou/kissa
Project-URL: Issues, https://github.com/yiochou/kissa/issues
License-Expression: MIT
License-File: LICENSE
Keywords: brainstorming,claude,notes,textual,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Requires-Dist: claude-agent-sdk<0.3,>=0.1
Requires-Dist: platformdirs>=4.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: textual<9,>=1.0
Description-Content-Type: text/markdown

# 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
