Felan

Get the job done. Waste less.
An open-source, model-portable coding agent built for cost-efficient, verifiable software work.

Felan is built around one rule: an optimization only counts when the task still succeeds. It combines model routing, progressive context, compact tool output, explicit task state, and estimated API-equivalent savings for supported optimizations.

Correctness first. Efficiency by design.

[!IMPORTANT] The local agent runs with your user's filesystem and process permissions. It is a host application, not a sandbox. Use an isolated host for untrusted projects or commands.

36.6% lower aggregate AI model cost in controlled benchmarks

Across six controlled, extension-specific comparisons, candidate configurations used $13.7132 versus $21.6297 for their baselines when summing median-reduced case costs—a 36.6% reduction. Individual results ranged from 5.2% to 66.0%. Each extension was measured separately against its disabled baseline, not as one all-enabled configuration. Every candidate met its configured quality gate.

View the methodology, cases, and full benchmark results

Install and run

Felan supports Node.js 22.19.0 or newer. Run the published package without a global installation:

npx @felan-ai/felan

Or install the felan command:

npm install --global @felan-ai/felan
felan

Connect a provider inside the TUI with /login, then start working:

felan "inspect this project and explain how to run its tests"
felan --continue
felan savings
felan --diagnostics
felan update

Initial messages start the interactive TUI by default. Use --mode text for a one-shot final response or --mode json for Pi-compatible JSONL session events. Both modes support --continue and exact --provider, --model, and --thinking selection. A verified global npm installation also supports the finite felan update command. See Getting started for first-run setup and Local CLI for all accepted commands, flags, and local state.

Efficient by design

Felan treats correctness as the constraint and cost as the optimization target. Fewer tokens can support that goal, but they are not the outcome: a cheaper run that fails is not an efficiency win.

Felan is developed against cost per verified task, not token count alone. The public harness-bench project holds the task, starting repository, verifier, timeout, and environment equivalent when comparing configurations. Correctness is primary; cost, token usage, and latency are supporting measurements. Read Efficient execution and savings for the measurement boundaries and claim limits.

Local agent, portable core

@felan-ai/felan is the account-free local terminal agent. The Felan cloud platform at felan.ai and app.felan.ai composes the same portable core and extensions as a managed host. Each host owns the boundaries that cannot be portable:

Read Architecture for the ownership boundary and Local memory architecture for the local versus host-managed memory lifecycle.

Built for software work

The extension catalog maps each workflow to its package, host boundary, commands, and runtime conditions.

Explicit host boundaries

Felan keeps the local host narrow in some places on purpose:

• only source-controlled built-in extensions are loaded;
• ambient Pi packages, extensions, prompts, themes, project settings, and package resources are filtered;
• model credentials and MCP OAuth tokens belong to the local host;
• web, document, browser, MCP, memory, and model-facing remote content are bounded and treated as untrusted; and
• missing binary dependencies degrade safely and require explicit interactive installation or disablement.

These controls do not sandbox ordinary shell or filesystem operations. Read the runtime and security guide before using Felan with sensitive repositories.

Architecture

Felan wraps Pi; it does not fork Pi. Pinned Pi packages provide the model, session, extension, and TUI primitives; Felan owns the host contracts, feature behavior, policy, storage, and presentation around them.

Behavior stays in its owning layer: apps/tui owns local policy, storage, and presentation; ext-* packages own portable feature behavior; and Agent Core owns adapter-neutral runtime contracts and base composition.

Documentation

The documentation hub routes readers by audience:

• Getting started
• Local CLI
• Configuration
• Commands and shortcuts
• Agents, tasks, and Prewalk
• Context and memory
• Web, MCP, browser, and documents
• Efficient execution and savings
• Architecture
• Runtime and security
• Comparisons with Codex, OpenCode, Claude Code, Pi, and Oh My Pi
• Contributing
• Release process

Repository map

Develop from source

Repository development and CI use Node.js 22.20.0 and pnpm 9.15.5:

git clone https://github.com/felan-ai/felan.git
cd felan
corepack enable
pnpm install --frozen-lockfile
pnpm build
node apps/tui/dist/cli.js

Run the complete build, type-check, test, license, packaging, and packed installation suite with:

pnpm verify

To review the Felan Pi themes in a browser, run pnpm theme:preview and open http://127.0.0.1:4173. Use pnpm theme:preview:check for a no-write validation or pnpm theme:preview:build to generate the ignored local artifact at .artifacts/theme-preview/index.html. The preview is a visual review aid; the Pi TUI remains the runtime source of truth.

See Contributing and the maintainer architecture map before changing a shared runtime or public package.

Community and license

Join the Felan Discord community to connect with users and contributors.

Felan is licensed under the MIT License. See NOTICE for third-party attribution and immutable upstream review details.