Felan

Felan Code

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

Felan Code 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.

41.9% lower aggregate AI model cost in controlled benchmarks

Across seven controlled, extension-specific comparisons, candidate configurations used $13.1193 versus $22.5774 for their baselines when summing median-reduced case costs—a 41.9% reduction. Individual results ranged from 14.5% 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 Code 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 attach the interactive TUI to the local daemon by default. Use --mode text for a one-shot final response or --mode json for Pi-compatible JSONL session events; both use the same persistent daemon and detach when their request finishes. CI/headless namespaces must be stopped explicitly. 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 commands, daemon lifecycle, and local state.

Sessions from Felan Code 0.28.3 and earlier appear in --resume, --continue and --session <id> for their recorded folder. Opening one adopts it in place: it keeps its ID and file, and new turns are appended to that file. Exit the old version first: refusing a session changed in the last few seconds is only a best-effort safeguard, and running 0.28.3 on an adopted session at the same time is unsupported. To copy a transcript into a new session ID instead, use /import. /export remains available.

Efficient by design

Felan Code 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 Code is developed against cost per verified task, not token count alone. The extension evaluations in evals/ hold 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 package for Felan Code, 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 Code keeps the local host narrow in some places on purpose:

• only source-controlled built-in extensions, explicitly requested local Pi extension paths, and host-enabled standard Pi extension directories are loaded;
• ambient Pi packages, 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.

Use repeatable --extension/-e flags to load local Pi extension files or directories for the interactive TUI, or set piExtensions.user / piExtensions.project in $FELAN_AGENT_DIR/settings.json to opt in to ~/.pi/agent/extensions and trusted <cwd>/.pi/extensions for all newly created root sessions, including ACP, headless and web sessions. Children inherit their root's extension paths. These extensions execute with the current user's permissions; Felan does not install network/package sources. Only a creating TUI that supports selection prompts can ask for folder trust. Other creators skip undecided project directories without saving a decision. Trust decisions are stored in $FELAN_AGENT_DIR/trust.json.

These controls do not sandbox ordinary shell or filesystem operations. Read the runtime and security guide before using Felan Code 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/felan owns CLI, TUI, ACP, headless, client-local themes, local service providers and the default host.json. apps/daemon owns admission, canonical session/process lifetime, persistence and interaction arbitration. Providers supply local configuration, credentials and runtime behavior through explicit contracts. ext-* packages own portable feature behavior, and Agent Core owns adapter-neutral contracts and base composition. Clients depend on the daemon; the daemon never depends on clients. See Extension services and generic UI.

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