A modular, hackable terminal coding agent built for long-running tasks and local models.
What is Fram?
Fram is a coding agent similar to Claude Code, Pi, or Tau (on which it is based). It is intended to perform well out of the box on complex and long-running tasks across a range of open models, incorporating accumulated lessons about effective context management, and how to mitigate the failure modes of small and locally hosted models. Philosophically, given a user directive Fram should continue to execute against that until successful, avoiding or recovering from any faults it encounters.
Hackability is a primary goal, Fram is written in Python and structured as a contributing fork of Tau, maintaining Tau's repo layout and conventions. If you want to extend it with your own memory, steering, or other integrations it should be easy to do so.
Install
Fram needs Python 3.12 or newer. Install it as its own tool with
uv:
uv tool install fram-agent
fram --version
The distribution is fram-agent because the shorter name fram is taken on
PyPI by an unrelated project. The command is still fram, and fram --version
names the Tau release it is based on.
Fram bundles Tau's own packages (tau_ai, tau_agent, tau_coding) under
their usual import names, so Tau extensions keep working. Because of that, it
replaces tau-ai in any environment it is installed into. Installing it as a uv
tool keeps it in an environment of its own.
Upgrade with:
uv tool upgrade fram-agent
(fram update is not currently supported, because Tau's updater would install
tau-ai. fram update --models still refreshes the model catalogs.)
Fram keeps its configuration and sessions in ~/.fram. Set TAU_HOME to use
another folder, including Tau's ~/.tau. Project .tau/ folders are shared
with Tau.
Quickstart
Run Fram from the project you want it to work on:
cd my-project
fram
Connect a model provider the first time with /login, choose a model with
/model, then type a request and press Enter:
explain what this project does
One-shot print mode is useful for scripts and quick prompts:
fram -p "summarize the architecture"
fram --cwd /path/to/project -p "find the CLI entry point"
Fram supports the same providers as Tau: OpenAI, Anthropic, OpenAI Codex subscription auth, OpenRouter, Hugging Face, and custom OpenAI-compatible endpoints, including local models. See Tau's providers guide.
Subagents
Fram ships with tau-subagents,
by Rian Dolphin, and turns it on by default. It gives the model an agent tool
that hands a task to a second, scoped session, in the foreground or in the
background, plus /agents to watch and steer those runs. The wheel also
installs tau-subagents' tau-job command, which runs long shell jobs in the
background.
Set FRAM_NO_SUBAGENTS=1 to start Fram without it. To try a different version,
load a checkout with fram -e /path/to/tau-subagents, which replaces the
bundled copy for that run.
The name
Fram is Norwegian for forward. It is the name of an exploration ship engineered to manage crushing polar ice through careful geometry, rather than trying to fight the forces directly.
License
Fram is released under the MIT License.
tau-subagents is copyright Rian Dolphin and is also released under the MIT
License. Its license ships in the wheel as tau_subagents/LICENSE.
Metadata
Release files for fram-agent 0.4.10.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fram_agent-0.4.10.4-py3-none-any.whl | Python 3 | none | any | Details for fram_agent-0.4.10.4-py3-none-any.whl |
Release files / fram_agent-0.4.10.4-py3-none-any.whl
| Download URL | fram_agent-0.4.10.4-py3-none-any.whl |
|---|---|
| Size | 839.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eecaace3e2f197a4f3fd74068615de752c4ca827618a019f2ea63c00de669695
|
|
BLAKE2b-256 checksum How to use checksums |
53ace41c20b97c6083d8ed537e88160740f52ca0b3dc13a200e9cc36e4e0e07f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| 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":true}
|
Security for fram-agent 0.4.10.4
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.