# Show HN: Felan – an open source coding agent focused on efficiency

> Source: <https://github.com/felan-ai/felan>
> Published: 2026-09-08 18:31:59+00:00

**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](https://felan-ai.github.io/harness-bench/results/2026-09-felan-extensions/benchmarks/subagents/results.html) | 100% | **23.7% lower** | — | 
| [MarkItDown](https://felan-ai.github.io/harness-bench/results/2026-09-felan-extensions/benchmarks/markitdown-cost/results.html) | 100% | **31.0% lower** | 13.8% fewer prompt tokens | 
| [Concise output](https://felan-ai.github.io/harness-bench/results/2026-09-felan-extensions/benchmarks/output-style-concise/results.html) | 100% | **14.5% lower** | 16.4% fewer output tokens | 
| [Prewalk](https://felan-ai.github.io/harness-bench/results/2026-09-felan-extensions/benchmarks/prewalk/results.html) | 100% | **66.0% lower** | — | 
| [RTK](https://felan-ai.github.io/harness-bench/results/2026-09-felan-extensions/benchmarks/rtk/results.html) | 83.3% | **26.6% lower** | 40.6% fewer prompt tokens | 
| [Codebase Memory](https://felan-ai.github.io/harness-bench/results/2026-09-felan-extensions/benchmarks/codebase-memory/results.html) | 100% | **5.2% lower** | 3.0% shorter agent-step duration | 

[View the methodology, cases, and full benchmark results](https://felan-ai.github.io/harness-bench/results/2026-09-felan-extensions/)

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](/felan-ai/felan/blob/main/docs/getting-started.md) for
first-run setup and [Local CLI](/felan-ai/felan/blob/main/docs/user-guide/local-cli.md) 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](https://github.com/felan-ai/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](/felan-ai/felan/blob/main/docs/concepts/efficient-execution.md) for the
measurement boundaries and claim limits.

`@felan-ai/felan` is the account-free local terminal agent. The Felan cloud
platform at [felan.ai](https://felan.ai) and
[app.felan.ai](https://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](/felan-ai/felan/blob/main/docs/concepts/architecture.md) for the ownership boundary
and [Local memory architecture](/felan-ai/felan/blob/main/docs/concepts/local-memory.md) 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](/felan-ai/felan/blob/main/docs/reference/extension-catalog.md) 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](/felan-ai/felan/blob/main/docs/concepts/runtime-and-security.md) before
using Felan with sensitive repositories.

**Felan wraps [Pi](https://github.com/earendil-works/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](/felan-ai/felan/blob/main/docs/README.md) routes readers by audience:

| Package | Purpose | Documentation | 
|---|---|---|
| [`@felan-ai/felan`](/felan-ai/felan/blob/main/apps/tui/README.md) | Cost-efficient, model-portable local coding agent and `felan` binary | [Local CLI](/felan-ai/felan/blob/main/docs/user-guide/local-cli.md) | 
| [`@felan-ai/agent-core`](/felan-ai/felan/blob/main/packages/agent-core/README.md) | Portable runtime contracts, prompt, tools, model tiers, and Pi composition | [Architecture](/felan-ai/felan/blob/main/docs/concepts/architecture.md) | 
| [`@felan-ai/ext-subagents`](/felan-ai/felan/blob/main/packages/ext-subagents/README.md) | Tracked asynchronous subagent protocol | [Agents and tasks](/felan-ai/felan/blob/main/docs/user-guide/agents-tasks-and-prewalk.md) | 
| [`@felan-ai/ext-tasks`](/felan-ai/felan/blob/main/packages/ext-tasks/README.md) | Dependency-aware root-session task graph | [Agents and tasks](/felan-ai/felan/blob/main/docs/user-guide/agents-tasks-and-prewalk.md) | 
| [`@felan-ai/ext-prewalk`](/felan-ai/felan/blob/main/packages/ext-prewalk/README.md) | Same-session planner-to-implementation handoff | [Agents and tasks](/felan-ai/felan/blob/main/docs/user-guide/agents-tasks-and-prewalk.md) | 
| [`@felan-ai/ext-ask-user`](/felan-ai/felan/blob/main/packages/ext-ask-user/README.md) | Structured one-to-four-question input | [Commands](/felan-ai/felan/blob/main/docs/user-guide/commands-and-shortcuts.md) | 
| [`@felan-ai/ext-context`](/felan-ai/felan/blob/main/packages/ext-context/README.md) | Progressive nested project context | [Context and memory](/felan-ai/felan/blob/main/docs/user-guide/context-and-memory.md) | 
| [`@felan-ai/ext-context-view`](/felan-ai/felan/blob/main/packages/ext-context-view/README.md) | Estimated context-window usage inspector | [Context and memory](/felan-ai/felan/blob/main/docs/user-guide/context-and-memory.md) | 
| [`@felan-ai/ext-insights`](/felan-ai/felan/blob/main/packages/ext-insights/README.md) | Local session analytics reports | [Commands](/felan-ai/felan/blob/main/docs/user-guide/commands-and-shortcuts.md) | 
| [`@felan-ai/ext-prompt-history`](/felan-ai/felan/blob/main/packages/ext-prompt-history/README.md) | TUI prompt-history picker | [Commands](/felan-ai/felan/blob/main/docs/user-guide/commands-and-shortcuts.md) | 
| [`@felan-ai/ext-memory`](/felan-ai/felan/blob/main/packages/ext-memory/README.md) | Portable local-first memory contracts | [Memory architecture](/felan-ai/felan/blob/main/docs/concepts/local-memory.md) | 
| [`@felan-ai/ext-output-style`](/felan-ai/felan/blob/main/packages/ext-output-style/README.md) | Validated concise, explanatory, and custom response instructions | [Configuration](/felan-ai/felan/blob/main/docs/user-guide/configuration.md#output-style) | 
| [`@felan-ai/ext-web-access`](/felan-ai/felan/blob/main/packages/ext-web-access/README.md) | Bounded web discovery and matching text/PDF passages | [Web access](/felan-ai/felan/blob/main/docs/user-guide/web-mcp-and-browser.md) | 
| [`@felan-ai/ext-mcp`](/felan-ai/felan/blob/main/packages/ext-mcp/README.md) | Portable OAuth-only remote MCP gateway | [MCP](/felan-ai/felan/blob/main/docs/user-guide/web-mcp-and-browser.md) | 
| [`@felan-ai/ext-felan-api`](/felan-ai/felan/blob/main/packages/ext-felan-api/README.md) | Single authenticated Felan API gateway | [Configuration](/felan-ai/felan/blob/main/docs/user-guide/configuration.md#felan-api) | 
| [`@felan-ai/ext-browser`](/felan-ai/felan/blob/main/packages/ext-browser/README.md) | Reviewed `agent-browser` CLI integration | [Browser](/felan-ai/felan/blob/main/docs/user-guide/web-mcp-and-browser.md) | 
| [`@felan-ai/ext-markitdown`](/felan-ai/felan/blob/main/packages/ext-markitdown/README.md) | Bounded office-document conversion | [Documents](/felan-ai/felan/blob/main/docs/user-guide/web-mcp-and-browser.md) | 
| [`@felan-ai/ext-background-bash`](/felan-ai/felan/blob/main/packages/ext-background-bash/README.md) | Detached Bash processes and logs | [Commands](/felan-ai/felan/blob/main/docs/user-guide/commands-and-shortcuts.md) | 
| [`@felan-ai/ext-codex`](/felan-ai/felan/blob/main/packages/ext-codex/README.md) | GPT-specific structured tools and request controls | [Configuration](/felan-ai/felan/blob/main/docs/user-guide/configuration.md) | 
| [`@felan-ai/ext-rtk-optimizer`](/felan-ai/felan/blob/main/packages/ext-rtk-optimizer/README.md) | RTK command rewriting and output compaction | [Runtime dependencies](/felan-ai/felan/blob/main/docs/reference/runtime-dependencies.md) | 
| [`@felan-ai/ext-codebase-memory`](/felan-ai/felan/blob/main/packages/ext-codebase-memory/README.md) | Structural code search, symbol reads, and bounded grep augmentation | [Runtime dependencies](/felan-ai/felan/blob/main/docs/reference/runtime-dependencies.md) | 
| [`@felan-ai/ext-powerline`](/felan-ai/felan/blob/main/packages/ext-powerline/README.md) | ANSI-aware local TUI footer | [Local CLI](/felan-ai/felan/blob/main/docs/user-guide/local-cli.md) | 
| [`@felan-ai/ext-session-title`](/felan-ai/felan/blob/main/packages/ext-session-title/README.md) | Automatic first-prompt session names | [Local CLI](/felan-ai/felan/blob/main/docs/user-guide/local-cli.md) | 

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](/felan-ai/felan/blob/main/CONTRIBUTING.md) and the
[maintainer architecture map](/felan-ai/felan/blob/main/docs/maintainers/architecture-map.md) before
changing a shared runtime or public package.

[Join the Felan Discord community](https://discord.gg/skNd4GSzZ) to connect with
users and contributors.

Felan is licensed under the [MIT License](/felan-ai/felan/blob/main/LICENSE). See [NOTICE](/felan-ai/felan/blob/main/NOTICE) for
third-party attribution and immutable upstream review details.