Skip to main content

pyt3client

PyPI License Package status Monthly downloads Distribution format Wheel availability Python version Implementation Releases Github Contributors Github Discussions Github Forks Github Issues Github Issues Github Watchers Github Stars Github Repository size Github last commit Github release date Github language count Github commits this month Package status PyUp

Read the documentation!

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 httpx and pydantic.

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)

Source distribution for pyt3client 0.2.0
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)

Table of built distributions (wheels) for pyt3client 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page