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.
-
-
Have Claude Code: nothing to run.
-
No Claude Code: install it with Anthropic's installer.
curl -fsSL https://claude.ai/install.sh | bash
-
Its "Setup notes" say
~/.local/bin is not in your PATH? The installer does not change your PATH itself. Add the folder with Anthropic's two lines for zsh, the Mac's shell:echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc
-
Claude Code asks you to sign in the first time you start it.
-
-
Homebrew or at least Apple's Command Line Tools. Homebrew installs the Command Line Tools for you (prerequisites), and the kit needs two of their tools: the plugin lines clone with git, and the ears build a Swift helper with
swiftc.-
Have Homebrew: nothing to run. It installed the Command Line Tools.
-
No Homebrew: get the Command Line Tools alone.
xcode-select --install
-
-
uv.
-
Have uv: nothing to run.
-
No uv: install it.
curl -LsSf https://astral.sh/uv/install.sh | sh
-
Then open a new terminal, so
uvis on your PATH. Or run:source ~/.zshrc
-
-
For a call on a Mac: Homebrew, then ffmpeg from it. A call needs ffmpeg, and Homebrew is how a Mac gets it. The Command Line Tools alone are not enough for a call.
-
Have Homebrew: go on to ffmpeg.
-
No Homebrew: install it with its own installer, from brew.sh.
-
Then install ffmpeg:
brew install ffmpeg
-
Homebrew lists what ffmpeg needs, then asks
Do you want to proceed with the installation? [y/n]. Pressy. It goes on at once, with no Return. -
Then the speech server, then link the phone: the phone bullets below.
-
A call without Homebrew is the workaround case. This guide does not cover it.
-
Then install the kit:
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.
-
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. -
To upgrade:
uv tool upgrade sessionkit
It keeps the Python the install chose.
-
To reinstall, give the pin again:
uv tool install --python 3.14 --reinstall sessionkit
Without it, uv drops the pin from its record, or, with
--force, builds the kit again on the Python it finds. -
A dialog may ask to install the Command Line Tools. On a Mac without them, the first
uv tool installopens it. Click Install and let it finish: the plugin lines need the git it brings. The dialog can open behind the Terminal window: look for it in the Dock or with Cmd-Tab. -
Phone calls are installed, and walked for a session started with
session start <name>. A fresh Mac took a real call and passed. A plainclaudesession does not hear calls you make to it yet. Whether the phone bot signs its mail to your Claude follows your mail carrier: bot mail signing. -
The speech server comes before the phone. A call hears you through it, so it is installed before you link your phone.
-
No phone: nothing to run now. Hearing and speaking installs the speech server with the rest of the voice.
-
A phone: first Homebrew, then ffmpeg, as the call item under "You need" says.
brew install ffmpeg
-
At Homebrew's
[y/n], pressy. -
Then install the speech server. It builds the server and fetches its weights, about 2.9 GB.
ears services install --only speech
-
Then link the phone. This makes its account on a public relay and prints the invite link. The name people see in their chat list goes in place of NAME:
sessionphone setup --name NAME
A name with a space in it needs quotes, or the shell splits it in two and setup refuses the second word:
sessionphone setup --name "Ada Lovelace"
-
The rest of linking is in sessionphone's docs.
-
-
Then quit Claude Code and start it again, every window of it, before you run anything else.
A plugin installed from the shell loads only when Claude Code starts, so a session that was already open has no plugin commands on its PATH, and no plugin hooks.
Then set up mail. This makes the box claude, which your first session
needs to hear mail and calls:
sessionkit setup
- On a fresh Mac it exits 4, and that is expected. It leaves two notmuch steps for later: the manual install shows its last lines.
The three install lines leave the ears without the model they listen with. Fetch it once:
ears install
It downloads the 2.3 MB voice-activity model from GitHub (one pinned
release of Silero VAD, checked against its SHA-256) to
~/.cache/ears/silero_vad.onnx, with no sudo, and prints done. Without
it the ears cannot hear you, and ears services install, the step that
starts them (hearing and speaking), refuses with
silero MISSING. The Swift helper is built later, when those services start.
-
The mail hooks start off. They tell an agent about new mail between its tool calls. To turn them on, set
"hooks": truein~/.sessionkit/mail/settings/mail.json. The plugin writes that file, with the hooks off, the first time a Claude Code session runs a tool, and it holds other settings too, so change only that key. Never write the file over: that deletes the other keys. This works whether the file is there yet or not, and whether it has ahookskey or not:f=~/.sessionkit/mail/settings/mail.json if [ -f "$f" ]; then perl -0777 -pi -e ' if (/"hooks"\s*:/) { s/"hooks"\s*:\s*false/"hooks": true/ } elsif (/\A\s*\{\s*\}\s*\z/) { s/\{\s*\}/{"hooks": true}/ } else { s/\{(\s*)/"{$1" . q("hooks": true,) . ($1 || " ")/e } ' "$f" else mkdir -p ~/.sessionkit/mail/settings echo '{"version": 1, "hooks": true, "sendmail": "drop"}' > "$f" fi
A
"hooks": falsebecomestrue. A file with nohookskey gets"hooks": trueas its first key, and its other keys stay as they were. If the file is not there yet, this writes what the plugin would have written, with the hooks on. The plugin never replaces a file that is already there.
Step by step, with every step that needs you marked: the manual install.
To see what this Mac is still missing, run the kit's check. It installs nothing. It prints one line for each thing the kit needs, and under each missing one, the command that adds it:
sessionkit doctor
It exits 0 when nothing the kit needs is missing, and 1 when something is. The phone bot and the session key are shown, but they never fail it.
-
No kit yet, or
sessionkitwill not start? The installer runs the same check. Its address is not live yet. From a clone of this repository, runbash install.sh --check. Once the address is live:curl -fsSL https://sessionkit.ai/install.sh | bash -s -- --check
Quick start
sessionkit --version
It lists the kit and each family package, with its version. Each X.Y.Z
is the version you installed:
sessionkit, version X.Y.Z
sessionmail X.Y.Z
sessiontools X.Y.Z
sessionphone X.Y.Z
sessionview X.Y.Z
sessionvoice X.Y.Z
Start Claude in a project folder, not in your home folder, where a new Terminal opens. Started in the home folder, Claude Code asks macOS for access to folders such as Desktop, Downloads, Photos and Media Library. Make a folder, go into it, and start Claude there:
mkdir -p ~/work && cd ~/work
session start
-
The first session on this Mac is
claude, and it hears Delta. Your phone's Delta messages and calls go to the boxclaude, and only the session that holdsclaudehears them. It says so as it starts:session start: this session is claude, the default seat on this host (box claude)
-
A second session starts plain. Start another the same way while the first one runs, and it is a plain Claude Code session. It does not hear Delta, and its one line names the session that holds
claude:session start: starting plain: the default seat claude is held by session 6161d8f8-d49f-4826-9f80-095bd2e6aaed (pid 6993, live 2s), so this session will NOT hear Delta messages or calls; that one does
-
Never a bare
claude. Mail to your agent's box, your phone's included, reaches only a session started as that agent. -
Without the box
claude, the first session starts plain too. The mail setup under Installation makes the box (first checks). The line names the repair:session start: starting plain: box claude is missing, so this session will NOT hear Delta messages or calls; repair: message setup --box claude
Then, from your agent inside a Claude Code session, list your live sessions:
session list
Mail another agent, its box name in place of TO:
message send TO -s "PR ready" -f note.md
Speak one line:
mouth say "the build is green"
-
Mail works inside a session.
messageandpagerread who is asking from the session. A plain terminal has no session, so they refuse withno 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 plays on your Mac's default output when no device is set.
mouth deviceslists the others, and--device DEVICEpicks one. -
To hear you, the ears need a speech-to-text server: hearing and speaking.
-
Your agent talks with the kit's mouth and ears. sessionvoice's ears skill sets the default:
With the kit, an agent talks through the kit's own mouth and ears: it speaks with
mouth sayand listens by arming the ears withears-arm. That is the default whenever the user asks it to talk, speak, listen or use voice, even on a host that also has VoiceMode'sconversetool. It usesconverseonly when the user asks for converse by name.
Requirements
- macOS (tested on macOS 27, Apple silicon)
- Linux
- WSL
- Windows
What the kit depends on, what needs each one, and how to upgrade it: dependencies.
Uninstall
claude plugin marketplace remove sessionkit
uv tool uninstall sessionkit
Removing the marketplace removes its six plugins too, but not the copies they ran from. Those copies, 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,pagerandmemoryover one maildir. - sessiontools: sessions, status and idle.
session. - sessionvoice: ambient voice.
earshears;mouthspeaks. - sessionphone: phone calls to a session over Delta Chat.
Installed, and walked on a fresh Mac for a session started with
session start <name>. A plainclaudesession does not hear calls you make to it yet. - sessionview: a tmux sidebar of your projects and your agents.
sessionview(said "session view").
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
make check
make install installs the kit editable, with uv. make check runs ruff,
shellcheck, then the tests.
The rules for changing the kit: AGENTS.md.
Status
Alpha, 0.3.2. Tested on macOS 27 on Apple silicon; Linux and Windows are untested. What you may still hit: known gaps.
Licence: AGPL-3.0.
Metadata
Release files for sessionkit 0.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sessionkit-0.3.2.tar.gz | 54.7 kB | Without provenance | Details for sessionkit-0.3.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sessionkit-0.3.2-py3-none-any.whl | Python 3 | none | any | Details for sessionkit-0.3.2-py3-none-any.whl |
Total release size: 106.3 kB
Release files / sessionkit-0.3.2.tar.gz
| Download URL | sessionkit-0.3.2.tar.gz |
|---|---|
| Size | 54.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6d81094b3df19a024c436211377d2ec6adebf23edf7726be57a25504d147ee2f
|
|
BLAKE2b-256 checksum How to use checksums |
a22bb23312ad43043217bb7642c6cd984ed6d18e8b1f55dd0afbd2ff7b0b5de7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / sessionkit-0.3.2-py3-none-any.whl
| Download URL | sessionkit-0.3.2-py3-none-any.whl |
|---|---|
| Size | 51.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
30835d07f96b423c4f691932bd5a7f1cd36af6228f8028d77561dbc3f79e03ca
|
|
BLAKE2b-256 checksum How to use checksums |
5004d131055656183e52e089f017c3c4a4626cf1e9432dd339dafcb5d0d4991e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for sessionkit 0.3.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.