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

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

Built distribution (wheel)

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

Total release size: 91.6 kB

Release files / pyt3client-0.1.1.tar.gz

Download URL pyt3client-0.1.1.tar.gz
Size 44.3 kB
Tags Source
SHA-256 checksum
How to use checksums
bb94e255564a9c66c8fd98bd60a398932f5836093d8cea0803d065d0f04bd927
BLAKE2b-256 checksum
How to use checksums
0f395acd78c43a95c903d9ba631d34417ddae225c289f73dcc329e6a95716121
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.1-py3-none-any.whl

Download URL pyt3client-0.1.1-py3-none-any.whl
Size 47.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6a25308e23a0935eefef180a8676acd8df58a4b6ce4d3afece13ee1e543cac1a
BLAKE2b-256 checksum
How to use checksums
71e8a55b83277f6e7a55b2e2fa5577b6765044f4be1e7bd168307ac8a714b045
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.1

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