SDK

Build context into your application.

Connect your application to Engine context, execution controls and portable state.

AvailableReviewed September 2026

Your host owns the workflow. LeanCTX provides the context and tool layer.

Choose an integration surface

Agent Tools provide project-scoped reads, search, composition and explicitly permitted writes or commands. Use them when you are building an agent’s tool layer.

Context lifecycle gives your application Session, Source, View, Plan and Receipt primitives. Your code prepares context, performs the host operation and records the outcome.

Your application owns the business workflow and authorization. Choose context-only preparation around your own model call, or governed Engine execution with permitted routes, budgets, retries and fallback. See Engine architecture.

Install Agent Tools

The commands below are a version-pinned SDK 1.1.0 reference example, paired with its declared Engine companion. They demonstrate that published interface; use the compatibility matrix and installation instructions shipped with your chosen SDK release for another version.

Start with a project-local virtual environment and Python 3.9–3.14. Calling its interpreter directly avoids activation scripts and PowerShell execution-policy changes.

macOS / Linux — Agent Tools:

python3 -m venv .venv
.venv/bin/python -m pip install "thinkery-leanctx-sdk[agent]==1.1.0"

On Linux, install your distribution’s Python venv support if python3 -m venv reports that it is missing. On macOS, use an installed Python 3 rather than assuming the system provides python.

The agent extra installs the exact Engine 3.10.1 companion required by SDK 1.1.0. The published certification matrix lists Linux x86_64 GNU and macOS ARM64. Other core release builds, including macOS Intel, Linux ARM64/musl and Windows, are not automatically SDK-certified.

Windows — Python SDK setup:

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install "thinkery-leanctx-sdk==1.1.0"

Use python instead of py -3 if your Python installation does not provide the launcher, after checking python --version. This installs the pure-Python SDK, without Agent Tools’ Engine companion. A Windows companion extra exists, but SDK 1.1.0’s pinned matrix does not certify Windows Agent Tools. Do not run the AgentContext examples below as if this base installation enabled them. Check the compatibility matrix before adding a native companion, or use an appropriate Linux environment with the listed artifact.

Core CLI installation and SDK installation are separate. A newer lean-ctx on PATH does not satisfy the SDK’s exact Engine, interface, schema and transport requirements.

Read your project

With Agent Tools installed on a compatible platform, run from a project containing a README.md, or change the path to a real file. Save the example as first_read.py and run it with .venv/bin/python first_read.py on macOS / Linux; a separately validated Windows Agent Tools setup uses .\.venv\Scripts\python.exe first_read.py.

from leanctx_sdk import AgentContext

with AgentContext(".", task="Understand this project") as tools:
    print(tools.tree(depth=2).text)
    print(tools.read("README.md").text)
    print(tools.metrics.saved_tokens)

This context is read-only by default. The metrics describe tool delivery; they do not prove answer quality or invoice savings.

Add capabilities deliberately

The stable Agent Tools surface includes AgentContext, AsyncAgentContext, AgentPermissions, ExecutionPolicy, ReadMode, ToolResult and AgentMetrics.

Writes and execution require explicit permissions. Execution also uses an allowlisted executable policy. Configure that policy when creating the context; a tool call cannot grant itself new permissions.

See the repository’s custom-agent guide for the exact permission and framework-adapter examples.

Task	Agent Tools surface	Permission
Inspect a project	`read`, `search`, `glob`, `tree`, `compose`, `symbol`	Read-only default
Change a file	`create_file`, `patch`, `replace_unique`	`write=True`
Run a command	`run(argv, …)`	`execute=True` and executable allowlist
Use a negotiated tool	`call(tool, arguments)`	The tool’s negotiated policy

For a command-enabled agent, pass structured arguments and a narrow policy. This example grants execution of git, not file-edit tools:

from leanctx_sdk import AgentContext, AgentPermissions, ExecutionPolicy

with AgentContext(
    ".",
    permissions=AgentPermissions(execute=True),
    execution_policy=ExecutionPolicy(
        max_timeout=30,
        allowed_executables=("git",),
    ),
) as tools:
    result = tools.run(("git", "status", "--short"))
    print(result.text)

The allowlist grants an executable, not only the particular subcommand shown here. Enforce any narrower workflow restrictions in your host. Shell strings are not accepted; environment forwarding requires allowed_env. The Engine validates executable resolution, arguments, environment and timeout.

Handle results and failures

ToolResult.text is the text delivery for your model. Keep content_blocks when your host supports image or binary content. For commands, inspect ToolResult.shell and its exit status as well as the text.

Failure	Host response
`EngineProtocolError`	Check the exact Engine, interface, schema and transport versions
`UnsupportedCapabilityError`	Use a supported surface or change the pinned integration
`AgentPermissionError`	Review the host’s policy; the tool cannot elevate itself
`EngineCrashed` / `EngineTimeout`	Report the failed operation and reconnect deliberately

There is no automatic retry of a mutation after a process failure. A timeout kills the Engine process; asynchronous cancellation terminates the in-flight process before returning cancellation. Reconnecting starts a new process and does not restore the previous process cache.

Prepare, use, complete

For the five-primitive lifecycle, create a ContextSession, prepare a ContextSource, and use the returned ContextView in your host operation. Inspect current_plan, then complete with an outcome to obtain a receipt; abort on an unsuccessful host step.

Recovery is an explicit operation and can fail when the source, policy or artifact is unavailable. Handle typed errors instead of silently substituting an empty context.

State transfer and compatibility

The Engine supports workspaces, checkpoints, deltas and handoffs for selected state. Match package format, Engine capabilities and recipient scope before resuming. A successful import does not make an outdated source current.

In the historical SDK 1.1.0 reference, these interfaces use leanctx_sdk.preview and sit outside that release’s Stable v1 commitment. That namespace describes the pinned package, not the full scope of the Engine. Use the manifest of your chosen SDK release for exact names and compatibility guarantees.

The core runtime and SDK have separate licensing. For embedding and redistribution, use the SDK licensing information and the license included with your chosen SDK release.

Sources & versions6 references Reviewed 17 Sept 2026

Core checkout: 0ce2207ee4
Installed runtime: 3.10.2
SDK release: 1.1.0

Separate baselines for source, CLI/configuration and SDK contracts. Review does not certify every platform or integration.

Versions & compatibility