Session Kit

Session Kit lets your Claude Code sessions mail each other, hear you and answer aloud. One install brings the five family packages and their Claude Code plugins.

Installation

You need macOS and Claude Code. If you do not have uv yet, install it with curl -LsSf https://astral.sh/uv/install.sh | sh, then open a new terminal (or run source ~/.local/bin/env).

uv tool install --python 3.14 sessionkit
claude plugin marketplace add sessionkit/sessionkit
claude plugin install sessionkit@sessionkit

The first line puts the commands on your PATH. The other two install the kit's plugin and the five family plugins it depends on. Start Claude Code (or restart it) to load them.

• Keep --python 3.14. Without it, uv takes the Python it finds: 3.15, where a voice library has no build yet and the install fails, or the Command Line Tools' 3.11. The kit is tested on 3.14.

• A dialog may ask to install the Command Line Tools. On a Mac without them, the first uv tool install opens it. Click Install and let it finish: the plugin lines need the git it brings.

• Phone calls are installed, not yet walked. Whether the phone bot signs its mail to your Claude follows your mail carrier: bot mail signing.

• The mail hooks start off. They tell an agent about new mail between its tool calls. To turn them on, set "hooks": true in ~/.sessionkit/mail/settings/mail.json. On a fresh install the file is not there yet, so make it:

  mkdir -p ~/.sessionkit/mail/settings
  echo '{"version": 1, "hooks": true}' > ~/.sessionkit/mail/settings/mail.json
  

  If the file is there, change only that key, because it can hold other settings:

  perl -pi -e 's/"hooks": *false/"hooks": true/' ~/.sessionkit/mail/settings/mail.json
  

Step by step, with every step that needs you marked: the manual install.

Quick start

sessionkit --version

It lists the kit and each family package, with its version:

sessionkit, version 0.2.1
  sessionmail   0.2.1
  sessiontools  0.2.0
  sessionphone  0.2.1
  sessionview   0.2.0
  sessionvoice  0.2.1

Start Claude with session start claude, never a bare claude: mail to your agent's box, your phone's included, reaches only a session started as that agent. sessionkit setup makes the box and the agent first: first checks.

Then, from your agent inside a Claude Code session:

session list                                     # your live sessions
message send <box> -s "PR ready" -f note.md      # mail another agent
mouth say --device default "the build is green"  # speak one line

• Mail works inside a session. message and pager read who is asking from the session. A plain terminal has no session, so they refuse with no seat in the environment ... set an identity (first checks). A send never makes a box: the address must have one already (mail between agents).
• The mouth needs a device. --device default is your Mac's default output; mouth devices lists the others.
• To hear you, the ears need a speech-to-text server: hearing and speaking.

Uninstall

claude plugin marketplace remove sessionkit
uv tool uninstall sessionkit

Removing the marketplace removes its six plugins too. The services and your data have their own steps: uninstall.

Usage

Every command answers --help, and each has a page: components.

The family

Session Kit installs these together:

• sessionmail: mail for coding agents. message, pager and memory over one maildir.
• sessiontools: sessions, status and idle. session.
• sessionvoice: ambient voice. ears hears; mouth speaks.
• sessionphone: phone calls to a session over Delta Chat. Installed, not yet walked.
• sessionview: a tmux sidebar of your projects and your agents.

Components

The commands, services and folders the install adds, and where each package logs: components.

Configuration

Each package configures itself: configuration. How the settings files stack: the settings guide.

Logs

Each package keeps its own log: logs. Which one to read for a symptom: troubleshooting.

Development

git clone https://github.com/sessionkit/sessionkit
cd sessionkit
make install    # editable: uv tool install -e .
make check      # ruff, shellcheck, then the tests

The rules for changing the kit: AGENTS.md.

Status

Alpha, 0.2.1. Tested on macOS 27 on Apple silicon; Linux and Windows are untested. What you may still hit: known gaps.

Licence: AGPL-3.0.