pyt3client
Thin, typed Python client for T3 Code
environments. It drives T3 Code's threads, projects and agents from Python through
the environment's MCP endpoint (/mcp), the interface T3 Code offers outside agents.
- Headless sign-in.
pair()turns a one-time pairing code into a 30-day token, without a browser. - Fully typed. Every one of the server's ~50 tools has generated Pydantic input and output models, taken from the JSON Schemas a real server advertises.
- Small. It depends only on
httpxandpydantic.
Quickstart
On the machine running T3 Code, create a pairing code:
t3 auth pairing create # or in the app: Settings -> Sharing & access
import asyncio
from pyt3client import T3Client, pair
from pyt3client.models.tools import (
ORCHESTRATOR_CAPABILITIES,
THREAD_LAUNCH,
THREAD_READ,
ModelSelection,
ThreadLaunchInput,
ThreadReadInput,
)
async def main() -> None:
# One time: spend the pairing code. Persist `credentials` (it is a pydantic model).
credentials = await pair("http://127.0.0.1:3773", "PAIRING-CODE", access="auto")
async with T3Client.from_credentials(credentials) as t3:
caps = await t3.call(ORCHESTRATOR_CAPABILITIES)
provider = caps.providers[0]
launched = await t3.call(
THREAD_LAUNCH,
ThreadLaunchInput(
project_id="<project id>",
title="Find slow tests",
message="Find why the test suite is slow.",
model_selection=ModelSelection(
instance_id=provider.provider_instance_id, model=provider.models[0].id
),
),
)
done = await t3.wait_for_thread(launched.thread_id, run_id=launched.run_id)
transcript = await t3.call(THREAD_READ, ThreadReadInput(thread_id=launched.thread_id))
print(done.status, [item.text for item in transcript.items])
asyncio.run(main())
Refusals raise T3ToolError with the server's code (for example thread_not_found
or capability_denied). For a tool newer than the bundled models, use
t3.call_raw(name, arguments).
Command line: pyt3
T3 Code's own t3 CLI only works on the machine running the server. pyt3
signs in once and then drives any environment it can reach, such as a homelab
box over Tailscale or a VPS over T3 Connect.
pip install "pyt3client[cli]"
pyt3 login https://box.tailnet.ts.net:3773 PAIRING-CODE --name box
pyt3 models # providers, models, options
pyt3 start /srv/app "Find why the tests are slow" \
--provider claudeAgent --model claude-haiku-5-5 --wait
pyt3 threads # or --search, --status, --project
echo "Now fix it" | pyt3 send <thread-id> - --wait
pyt3 show <thread-id> # state + latest messages
pyt3 pending <thread-id> # questions the agent waits on
pyt3 answer <thread-id> <request-id> color=red
pyt3 interrupt <thread-id>
start takes a project id or any folder inside a project. Relative paths resolve
against your shell, which only makes sense when the server runs on this machine.
Every command takes --json. With several saved environments, pick one with
--env <alias> or PYT3_ENV.
start, send --wait and wait exit like upstream t3 thread --wait:
0 when the run completed, 1 when it failed (or on any error), 2 when the agent
waits for an answer or approval, and 3 when --timeout ran out.
Tokens are saved in $XDG_CONFIG_HOME/pyt3client/credentials.json (mode 0600).
pyt3 envs lists them without the tokens. pyt3 logout forgets one; revoke it in
T3 Code under Settings -> Sharing & access.
Access levels
pair(..., access=...) picks what the client may do. A thread the client starts
or steers can never run above this level. To narrow it further for one client, pass
T3Client(..., mode_limit=("approval-required", "plan")).
| Level | Can |
|---|---|
read-only |
read projects, threads, providers, models |
approval-required … auto |
also start, message, wait for and stop threads |
full-access |
also create, update and delete projects |
Use https, localhost or Tailscale HTTPS addresses. Over plain http on a LAN,
the pairing code and token travel unencrypted.
Development
See CLAUDE.md for the upstream map: where each protocol detail lives in the t3code repository, how the models are generated, and how to test against an isolated server.
Metadata
Release files for pyt3client 0.2.0
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 |
|---|---|---|---|---|
| pyt3client-0.2.0.tar.gz | 53.9 kB | With provenance | Details for pyt3client-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyt3client-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for pyt3client-0.2.0-py3-none-any.whl |
Total release size: 112.3 kB
Release files / pyt3client-0.2.0.tar.gz
| Download URL | pyt3client-0.2.0.tar.gz |
|---|---|
| Size | 53.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8b2885124dd48077aff52c722527e8a4c39d3d121b4eeec1dd860c7919bc644f
|
|
BLAKE2b-256 checksum How to use checksums |
48addb7d6f68d24955448b553ac282f387776ad8e0c91e228bf176c089aaec93
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logRelease files / pyt3client-0.2.0-py3-none-any.whl
| Download URL | pyt3client-0.2.0-py3-none-any.whl |
|---|---|
| Size | 58.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c4ee97d9e0f591754f664909131e0666e422e3dee52fc6415ba1b379e06f3810
|
|
BLAKE2b-256 checksum How to use checksums |
47fd9a65d7e04020978790e5112cf24b9fbeb6d35743c557e35dfe0b13edf393
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logSecurity for pyt3client 0.2.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pyt3client-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logA 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.