Skip to main content

Fram — modular coding agent for long tasks and open models. A drawing of the polar ship Fram beset in pack ice.

A modular, hackable terminal coding agent built for long-running tasks and local models.

GitHub · Tau documentation


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, and reads project resources from .fram/ folders. Set TAU_HOME to use another home, including Tau's ~/.tau, and TAU_PROJECT_DIRNAME=.tau to share Tau's project folders.

Fram before 0.4.10.5 read project resources from .tau/. A project's .tau/ skills, SYSTEM.md, AGENTS.md, extensions and subagent settings no longer load under Fram: rename the folder to .fram, or set TAU_PROJECT_DIRNAME=.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.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for fram-agent 0.4.10.5
File Interpreter ABI Platform Actions
fram_agent-0.4.10.5-py3-none-any.whl Python 3 none any Details for fram_agent-0.4.10.5-py3-none-any.whl

Release files / fram_agent-0.4.10.5-py3-none-any.whl

Download URL fram_agent-0.4.10.5-py3-none-any.whl
Size 851.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4360dcc3fc6d69949cf714bb032e9507556d843e0669f4f37f7d7cd4f916235c
BLAKE2b-256 checksum
How to use checksums
3672eb6d54a334951df38618824e1d0461abc245a7ac4cfd9bdfb92b984fd262
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","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.5

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