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.
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.
| Extension | Quality vs baseline | Cost vs baseline | Secondary result |
|---|---|---|---|
| Subagents | 100% | 23.7% lower | — |
| MarkItDown | 100% | 31.0% lower | 13.8% fewer prompt tokens |
| Concise output | 100% | 14.5% lower | 16.4% fewer output tokens |
| Prewalk | 100% | 66.0% lower | — |
| RTK | 83.3% | 26.6% lower | 40.6% fewer prompt tokens |
| Codebase Memory | 100% | 27.8% lower | 7.8% shorter agent-step duration |
| Session Compaction | 100% | 45.2% lower | 52.1% fewer prompt tokens |
View the methodology, cases, and full benchmark results
Felan Code supports Node.js 22.19.0 or newer. Run the published package without a global installation:
npx @felan-ai/felanOr install the felan command:
npm install --global @felan-ai/felan
felanConnect 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 updateInitial 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.
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.
| Boundary | What Felan Code does |
|---|---|
| Model routing | Prewalk can start a task with a stronger planner and continue the same conversation trajectory on a configured implementation model. |
| Context control | Progressive nested instructions, scoped subagents, lazy MCP discovery, and bounded research keep context focused on the current work. |
| Tool output | RTK-backed command rewriting and post-tool compaction reduce noisy model input while preserving failures, complete JSON, and recoverable output. |
| Explicit state | Dependency-aware tasks, structured questions, retained subagent records, and local project memory keep decisions and progress inspectable. |
| Measurement | /savings, felan savings, and the Powerline footer report estimated API-equivalent cost avoided by supported optimizations. |
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.
@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:
| Felan Code | Felan cloud platform |
|---|---|
Runs on your machine from @felan-ai/felan |
Runs as managed background agents |
| Uses provider-owned local credentials; no Felan account required | Adds tenant/team workflows, integrations, visibility, and guardrails |
| Stores sessions and project memory under the local agent directory | Provides host-managed storage, credentials, and integrations |
| Applies a fixed source-controlled built-in and resource policy | Chooses the managed host's policy and integrations |
Read Architecture for the ownership boundary and Local memory architecture for the local versus host-managed memory lifecycle.
| Workflow | What Felan Code adds |
|---|---|
| Delegate and inspect | Tracked asynchronous subagents with bounded nesting, live transcripts, steering, continuation, cancellation, and completion notices. |
| Plan and hand off | A shared task graph with prerequisites, ownership, acceptance criteria, ready/blocked views, verified results, and same-session Prewalk model routing. |
| Ask instead of guessing | Searchable one-question and one-to-four-question wizards with multi-select, freeform answers, comments, and timeout handling. |
| Load context where it applies | Cwd instructions plus progressive nested AGENTS.md/CLAUDE.md discovery and explicit Agent Skills. |
| Remember locally | An account-free, project-scoped Markdown wiki with bounded evide B074 nce ingestion, validation, citations, and retryable host-owned publication. |
| Retrieve web evidence | Provider-backed URL discovery, bounded matching text/PDF passages, and explicit SSRF-untrusted remote content boundaries. |
| Connect external tools carefully | A lazy OAuth-only remote MCP gateway, explicit credential ownership, and bounded untrusted remote results. |
| Use the right model tools | Shared read/bash tools with background processes, GPT-specific apply_patch, and RTK-backed command/output optimization. |
| Inspect efficiency | Session, project, and retained local estimates through /savings, felan savings, and the default Powerline footer. |
| Keep the TUI readable | Grouped tool activity, full-call inspection, agent/task/process overlays, and an ANSI-aware Powerline footer. |
The extension catalog maps each workflow to its package, host boundary, commands, and runtime conditions.
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.
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.
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
| Package | Purpose | Documentation |
|---|---|---|
@felan-ai/felan |
Felan Code and the felan binary |
Local CLI |
@felan-ai/daemon |
Session daemon, admission and canonical execution lifetime | Services and UI |
@felan-ai/agent-core |
Portable runtime contracts, prompt, tools, model tiers, and Pi composition | Architecture |
@felan-ai/ext-subagents |
Tracked asynchronous subagent protocol | Agents and tasks |
@felan-ai/ext-tasks |
Dependency-aware root-session task graph | Agents and tasks |
@felan-ai/ext-prewalk |
Same-session planner-to-implementation handoff | Agents and tasks |
@felan-ai/ext-ask-user |
Structured one-to-four-question input | Commands |
@felan-ai/ext-context |
Progressive nested project context | Context and memory |
@felan-ai/ext-context-view |
Estimated context-window usage inspector | Context and memory |
@felan-ai/ext-insights |
Local session analytics reports | Commands |
@felan-ai/ext-prompt-history |
TUI prompt-history picker | Commands |
@felan-ai/ext-memory |
Portable local-first memory contracts | Memory architecture |
@felan-ai/ext-output-style |
Validated concise, explanatory, and custom response instructions | Configuration |
@felan-ai/ext-web-access |
Bounded web discovery and matching text/PDF passages | Web access |
@felan-ai/ext-mcp |
Portable OAuth-only remote MCP gateway | MCP |
@felan-ai/ext-felan-api |
Single authenticated Felan API gateway | Configuration |
@felan-ai/ext-browser |
Reviewed agent-browser CLI integration |
Browser |
@felan-ai/ext-markitdown |
Bounded office-document conversion | Documents |
@felan-ai/ext-background-bash |
Background processes, PTY input, and logs | Commands |
@felan-ai/ext-codex |
GPT-specific structured tools and request controls | Configuration |
@felan-ai/ext-rtk-optimizer |
RTK command rewriting and output compaction | Runtime dependencies |
@felan-ai/ext-codebase-memory |
Structural code search, symbol reads, and bounded grep augmentation | Runtime dependencies |
@felan-ai/ext-powerline |
ANSI-aware local TUI footer | Local CLI |
@felan-ai/ext-session-title |
Automatic first-prompt session names | Local CLI |
@felan-ai/ext-session-compaction |
Bounded verified session compaction and active-lineage recall | Context and memory |
Repository development and CI use Node.js 22.23.4 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/felan/dist/cli.jsRun the complete build, type-check, test, license, packaging, and packed installation suite with:
scripts/test-isolated.sh pnpm verifyTo review the Felan Code 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.
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.