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.
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.
| 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% | 5.2% lower | 3.0% shorter agent-step duration |
View the methodology, cases, and full benchmark results
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.
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.
| Boundary | What Felan 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 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.
@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:
| Local Felan | 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 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 evidence 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 | GPT-specific structured command/patch/image tools, detached Background Bash for other providers, 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 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.
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.
The documentation hub routes readers by audience:
| Package | Purpose | Documentation |
|---|---|---|
@felan-ai/felan |
Cost-efficient, model-portable local coding agent and felan binary |
Local CLI |
@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 |
Detached Bash processes 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 |
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.
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.