Metadata-Version: 2.4
Name: tellmphone
Version: 0.1.0
Summary: Let your LLMs call each other — a local MCP switchboard for coding agents
Project-URL: Homepage, https://github.com/CaliforniaOpenSource/tellmphone
Project-URL: Repository, https://github.com/CaliforniaOpenSource/tellmphone
Project-URL: Issues, https://github.com/CaliforniaOpenSource/tellmphone/issues
Author-email: Kevin Dewald <kevin@californiaopensource.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,claude,codex,llm,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: mcp>=1.2
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# TeLLMphone ☎️

**Let your LLMs call each other.**

TeLLMphone is a local MCP server that lets coding agents place calls to each
other. Claude Code can ring Codex with a question about the current project
and get an answer back, keep that conversation going across multiple turns,
or leave a voicemail for the next Codex session to pick up. Conversations
survive interruptions on both sides, and the callee can be given a saved
personality and a specific model.

The second opinion you want is usually installed on the same machine, one
terminal over — and you're tired of being the copy-paste layer between two
AIs. Now they can just call each other.

Currently supports Claude Code and Codex; other agents can be added as
plugins.

## Requirements

- macOS or Linux
- Python 3.11+ and [uv](https://docs.astral.sh/uv/)
- The agent CLIs you want to connect (`claude`, `codex`), installed and
  logged in

## Install

```bash
uv tool install tellmphone   # or: pipx install tellmphone
tellmphone install
```

`install` registers the MCP server with every agent CLI it finds — via
`claude mcp add` and `codex mcp add` — and sets the codex config needed for
non-interactive tool approval. It is idempotent; rerun it if you move the
checkout. `tellmphone uninstall` removes the registrations (it does not
delete `~/.tellmphone/`).

## Usage

You talk to your agent; your agent works the phone. In a Claude Code
session:

> Call codex and get a second opinion on this migration. Use the
> grumpy-reviewer personality.

Claude will place the call, relay the answer, and can keep the thread going
with follow-ups. In the other direction, start a Codex session in the same
project and ask it to check its messages.

The tools the agents get:

| Tool | What it does |
|---|---|
| `call` | Send a message to another agent about a project. Optional personality and model. Waits for the answer, or leaves it as voicemail. |
| `reply` | Follow up on an existing call. The callee resumes with full context. |
| `check_messages` | List unread messages and open calls for a project. |
| `hang_up` | Close a call. The transcript is kept. |
| `phonebook` | List available agents and personalities. |

## How it works

```
┌─────────────┐   MCP (stdio)   ┌──────────────────┐   headless CLI   ┌─────────────┐
│ Claude Code │ ──────────────► │   TeLLMphone     │ ───────────────► │ codex exec  │
│  (caller)   │  call/reply/…   │   switchboard    │  spawn / resume  │  (callee)   │
└─────────────┘                 └──────────────────┘                  └─────────────┘
```

There is no daemon. Each agent runs its own TeLLMphone instance over stdio;
shared state lives under `~/.tellmphone/`. A call spawns the callee's CLI
headlessly (`codex exec`, `claude -p`) in the project directory, records the
callee's native session id under a stable call id, and replies resume that
exact session (`codex exec resume`, `claude --resume`). If a native session
is lost, the stored transcript is replayed into a fresh one. Callees run in
their CLI's read-only/sandboxed mode unless you allowlist a project for
writes, and a hop limit keeps agents from chaining calls indefinitely.

The internals lean into the name: the switchboard routes calls, the
phonebook lists who you can dial, a busy line means the callee is still
thinking, voicemail holds messages for agents that aren't running, and the
hop limit stops two agents from playing telephone forever.

Details, including the security model, are in [docs/DESIGN.md](docs/DESIGN.md).

## Configuration

`~/.tellmphone/config.toml`:

```toml
[defaults]
timeout_s = 300   # wait this long before a live call rolls to voicemail
max_hops = 2      # agent-to-agent chain depth limit

# default model per callee; a call's explicit model argument wins.
# Use whatever model ids your CLI accepts.
[agents.codex]
model = "gpt-5.5"

# callees run read-only unless a project is allowlisted here
[permissions."/path/to/project"]
write = true
```

Personalities are Markdown files in `~/.tellmphone/personalities/` with a
small frontmatter block (`name`, `description`) followed by the system
prompt. Three starters are installed on first run (`grumpy-reviewer`,
`security-auditor`, `rubber-duck`); add your own alongside them. Callers
select personalities by name and never send system prompts inline.

## Data

Call records and transcripts live under `~/.tellmphone/projects/`.
Transcripts contain whatever flowed through the conversation, which for a
coding agent usually includes your code. Everything is plain JSON owned by
your user; delete a call directory (or all of `~/.tellmphone/`) to purge.

## Development

```bash
uv sync
uv run pytest
```

The test suite runs against fake `claude`/`codex` executables, so it needs
neither CLI installed nor network. From a checkout, `uv run tellmphone
install` registers your development version with your agents.

---

TeLLMphone is a project powered by
[The California Open Source Company](https://www.californiaopensource.com).
Licensed under [Apache 2.0](LICENSE).
