v0.2.0 (beta)

thunc 0.2 adds agents: typed functions that can look around before they answer. An agent lists, reads and searches files in a working directory, and, when its permissions allow, writes, edits and runs commands, then returns a checked value of your return type.

pip install --upgrade thunc

import thunc

repo = thunc.Agent("repo-guide", workdir="~/code/myapp")


@repo.task
def request_timeout() -> int:
    """Find the HTTP request timeout this app uses, in seconds."""
    ...


request_timeout()  # -> 45, after the agent searched the code and read the file that sets it

Agents

• thunc.Agent and @agent.task: tasks are declared like @thunc.function, sync or async. @thunc.agent(name, workdir=...) declares a one-task agent in one go, and agent.call(...) runs a task built in code (#23, #34).
• Permissions: by default an agent reads everything in workdir and writes nothing. Rules such as ["write:src/**", "run:pytest", "!read:.env*"] open up the write, edit and run tools; a deny always wins. Every path must stay inside workdir, and a file is only edited after the agent read it in the same run (#26, #28).
• Commands run without a shell, with a minimal environment (your API keys don't reach them) and a time limit that also stops their child processes. Permissions are not a sandbox: run:pytest runs the project's code (#28).
• Your own functions as tools: tools=[open_issue]; arguments are checked against the type hints (#34).
• Memory between runs: the agent saves notes with remember. They're kept in .thunc_agents/<name>/memory.md, a plain file you can edit, along with one JSONL record per run (#23).
• A record of each run: agent.run(task, ...) returns a thunc.Run with the value, files changed (by edits and by commands), commands, denials and steps. A failed run raises thunc.AgentError carrying the partial record (#29, #34).
• Instruction files: follow=True gives the agent AGENTS.md / CLAUDE.md as instructions. It's off by default, so a folder you point an agent at can't instruct it (#31).
• Native tool calls on the Claude and OpenAI APIs, with the fixed part of the prompt cached. Claude Code and Codex use a JSON text protocol (#32).
• System prompt presets: thunc.prompts.CODING, CODE_REVIEW and ANALYSIS for system= (#34).
• Limits: max_steps=40 and timeout= (seconds) per run (#34).

Tested

• Offline tests run on Python 3.10–3.14 on Ubuntu, and now on Windows.
• Live agent tests passed on Claude Code, Codex, the Claude API and the OpenAI API.
• A prompt evaluation (live_tests/eval_prompts.py) passed 90/90 runs on the Claude API and Claude Code. The tasks are too easy to tell the prompt versions apart, so the presets are opt-in.

Behaviour changes

• thunc.agent is now the @thunc.agent decorator. from thunc.agent import Agent still works.
• Agents refuse the jev backend before a run starts; use Jev with @thunc.function.
• Nothing changes for @thunc.function and thunc.call.

Still beta: expect bugs, and the agent API may change. The new CHANGELOG.md lists every release.

Full changelog: v0.1.3...v0.2.0