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.1.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.1.0
File Size Uploaded Provenance Actions
pyt3client-0.1.0.tar.gz 44.0 kB Without provenance Details for pyt3client-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyt3client 0.1.0
File Interpreter ABI Platform Actions
pyt3client-0.1.0-py3-none-any.whl Python 3 none any Details for pyt3client-0.1.0-py3-none-any.whl

Total release size: 91.1 kB

Release files / pyt3client-0.1.0.tar.gz

Download URL pyt3client-0.1.0.tar.gz
Size 44.0 kB
Tags Source
SHA-256 checksum
How to use checksums
d2aa1361c0a5e17ed43bdc635075673f91698be9dc8ab247b59cbdb97f62bc29
BLAKE2b-256 checksum
How to use checksums
fc0ee61706a998684c3dd65b9e196b581cdcd066f46db1e05317cfc362052aa6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / pyt3client-0.1.0-py3-none-any.whl

Download URL pyt3client-0.1.0-py3-none-any.whl
Size 47.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c23f3096a463dc169814e860453c9afe517a3abfc98281028430fddc3815eff3
BLAKE2b-256 checksum
How to use checksums
ebaf04a8f57cdb61186af37c405ab7c26b203652d3fba9f12dc4cce9718ae9a0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for pyt3client 0.1.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.

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.

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