# Configuration Felan Code keeps local configuration under one agent directory. Unless noted otherwise, paths below are relative to `$FELAN_AGENT_DIR`, which defaults to `~/.felan`. ## Configuration files | Path | Purpose | | --- | --- | | `.env` | Optional `KEY=value` environment variables for the daemon, such as `FELAN_API_KEY`; they override variables inherited from the client that started the daemon and apply on the next daemon start | | `settings.json` | Local host configuration provider: built-in enablement, extension behavior, model scope, and subagent limits | | `tui/settings.json` | Client-owned theme, keybindings, and terminal display preferences | | `trust.json` | Remembered folder trust for optional project Pi extensions | | `models.json` | Pi provider credentials, custom models, and model metadata overrides | | `APPEND_SYSTEM.md` | Optional local application prompt append | | `mcp.json` | Felan-owned remote OAuth MCP servers | | `/.mcp.json` | Project MCP entries; higher precedence by server name | | `agents/*.md` | Felan-specific user agent definitions | | `themes/*.json` | Client-local user themes; same JSON `name` as `felan-light` or `felan-dark` shadows the packaged theme | The local host does not read Pi project settings. Configuration for ambient Pi extensions, prompts, packages, themes, or skills is filtered by default. Load a external extension explicitly from a local client with repeatable `--extension`/`-e` flags, or opt in to Pi's standard directories with `piExtensions` as described below. Neither path installs network or package sources. ## Settings Built-ins controlled by `builtinExtensions` are enabled unless their key is explicitly `false`. Native code mode is separately opt-in. The example below shows available Felan-specific settings and intentionally disables the browser and Powerline extensions: ```json { "builtinExtensions": { "subagents": true, "askUser": true, "tasks": true, "prewalk": true, "mcp": true, "felanApi": true, "modelTools": true, "fusion": true, "webAccess": true, "browser": false, "backgroundBash": true, "codex": true, "claudeCode": true, "rtkOptimizer": true, "codebaseMemory": true, "markitdown": true, "context": true, "contextView": true, "insights": true, "promptHistory": true, "memory": true, "sessionCompaction": true, "outputStyle": true, "powerline": false, "sessionTitle": true }, "extensionConfig": { "prewalk": { "entryApproval": "allow", "planReview": "skip" }, "outputStyle": { "style": "concise" }, "codebaseMemory": { "maxCacheBytes": 0 }, "codex": { "verbosity": "low", "forceCachedWebSockets": true, "postAgentRunCompaction": true, "imageGeneration": true }, "claude-code": { "plan": "pro", "longContextExtraUsage": false }, "sessionCompaction": { "method": "summary", "model": "inherit", "compactBeforeCacheExpiry": true, "minContextTokens": 200000 }, "fusion": { "participants": [], "fusionModel": "inherit", "concurrency": 4, "timeoutSeconds": 120, "maxOutputChars": 12000, "thinking": "off" } }, "felanSubagents": { "concurrency": 4, "maxDepth": 3 }, "felanClassifier": { "model": "auto" }, "codemode": { "mode": "off" }, "piExtensions": { "user": false, "project": false, "llamaCpp": false } } ``` Defaults: - every `builtinExtensions` entry is enabled; - native code mode is `off`; - memory processing follows `builtinExtensions.memory` and changes apply when Felan Code next constructs a root session; - response output style is `concise`; - classifier model selection is `auto`; - subagent concurrency is `4` and maximum nesting depth is `3`; - editor horizontal padding is `1`; - tool display is `grouped`; - Fusion has no participant models until selected in the interactive TUI; - local memory processing is enabled; and - `piExtensions.user`, `piExtensions.project`, and `piExtensions.llamaCpp` are `false`. ### Pi llama.cpp integration Set `piExtensions.llamaCpp` to `true` in Felan's global `settings.json` to enable Pi's bundled llama.cpp provider and model-management commands for root sessions created by any client, but not child sessions. It is off by default and does not enable Pi's other built-in extensions or ambient extension discovery. The external Hugging Face `pi-llama` package is separate and is not enabled by this setting. Restart or resume the root session to apply the change. Felan does not install or start llama.cpp. Start an existing llama.cpp router server, then use `/login llama.cpp` to configure its URL and optional API key. Set `LLAMA_BASE_URL` and optionally `LLAMA_API_KEY` instead if you prefer environment configuration. Use `/llama` to inspect and manage router models, then `/model` to select one for the session. Downloads are explicit actions in Pi's `/llama` interface; enabling the integration does not download models. ### Code mode Select **Code mode** in `/settings`, or set `codemode.mode` to `off`, `on`, or `only` in `settings.json`: ```json { "codemode": { "mode": "on" } } ``` - `off` (default) does not register Felan's native Pi code-mode extension. - `on` activates `codemode` alongside direct tools for programmatic batching, filtering, and computation. - `only` activates `codemode` and hides callable direct-tool declarations from model requests. Those tools remain callable from scripts. Pi's model-only tools remain directly available and cannot be called from scripts. Changes apply when Felan constructs a new root runtime, including restart or resume. Interactive, headless, and ACP roots use the setting; subagents inherit their root's mode even if the saved setting changes later. Inspection profiles still restrict nested calls, and tool-free synthesis does not reactivate code mode. Memory dream sessions retain their separate restricted tool set. Felan uses Pi's `createCodemodeExtension({ mode, models: false })`. `models: false` removes the sandbox's `models.*` catalog, classifier, and image-generation helpers; it does not change the session model or disable ordinary tool calling. Enabled Felan model tools remain available through their normal policy-governed paths. Nested calls use the normal validation, tool hooks, cancellation, and audit pipeline; code mode does not isolate tools from the host's permissions. The configuration keeps Pi's object shape and preserves other native fields, such as `codemode.inlineBudget`. Avoid loading a second code-mode factory through an explicit Pi extension when using the built-in integration. `off` controls Felan's integration, not separately loaded extensions. ### Runtime resources and session behavior External extensions are configured per host, not per session or client. `piExtensions.user` loads `~/.pi/agent/extensions`; `piExtensions.project` loads `/.pi/extensions` only after a Felan folder-trust decision stored in `$FELAN_AGENT_DIR/trust.json`. Both default to `false` and apply to every new root: TUI, ACP, headless/print mode, web-created sessions through the remote connector, and `session.import`. Only the TUI creating a session asks about a folder without a trust decision. ACP, headless and web creates skip that folder without saving a decision, so a later TUI create can still ask. Folders already trusted directly or through a parent load for every creator. Trust authorizes those extension files only; it does not load Pi project settings, packages, skills, prompts, or themes. `--extension`/`-e` remains additive for local clients; remote creates cannot supply explicit paths. External extension paths are fixed at creation. Resume keeps saved paths, clone/fork keep the source session's paths, and adopting an existing unindexed transcript on attach loads no external extensions. `-e` passed while resuming is ignored with a notice and applies to new sessions. Children, including subagents, execution children and workers, load the same external extension paths as their root; a worker's tool allowlist still limits its active tools. Enabling these settings runs external extension code with your permissions in ACP, headless, web-created and child sessions as well as the TUI. `builtinExtensions.sessionTitle` controls automatic names for interactive root sessions. Disable it to keep the first prompt as the session-picker fallback. When no saved or resumed model is usable, Felan Code selects from its own curated provider defaults instead of Pi's defaults. Both `openai` and `openai-codex` currently use `gpt-5.6-sol`. A successful first login selects and saves that provider's Felan default only when the session does not already have an active model. In `/model`, Enter saves the highlighted model as the default for future sessions; Ctrl+S changes only the current session. `builtinExtensions.sessionCompaction` controls verified session compaction and active-lineage `session_recall`. It is enabled by default. Disable it to use Pi's native compactor and remove the recall tool. `extensionConfig.sessionCompaction.method` defaults to `summary`, Felan's fresh verified summary. Set it to `classifier` for fast, opt-in transcript compaction when an authenticated classifier model is available through Pi's runtime. This is not a measured cost saving. Classifier mode sends bounded compaction evidence to the selected classifier provider and makes no summary-model request on success. Without a classifier or on classifier request failure, it falls back to the verified summary. Ordinary compaction falls back to native Pi if the summary is unavailable or fails. Cancellation stops this chain. The summary method does not classify evidence and disables cache retention for its bounded summary request. `FELAN_LOG_LEVEL` controls the host logger (default `debug`); session-compaction and subagent-routing classifier traces go to `storage('agent')/logs/felan.jsonl`. Subagent routing records the generated guidance and scored/selected agent IDs, but not the request or conversation state. `extensionConfig.sessionCompaction.model` defaults to `inherit`, which uses the active session model. It also accepts `xhigh`, `high`, `medium`, and `low`; each selects an exact tier from the allowed session catalog, preferring the active provider/family before crossing providers. If no model exists in the requested tier, compaction falls back to `inherit`. The setting is also available in `/settings` and through `--session-compaction-model low`, and applies to a newly constructed runtime. `extensionConfig.sessionCompaction.compactBeforeCacheExpiry` defaults to `true`. At turn end, and on session start, tree navigation, or model change, it starts a countdown to about 20 seconds before a known cache expiry. It runs only if the agent remains idle with nothing queued, Pi auto-compaction is not disabled (`pi.getSettings().compaction.enabled !== false`), and context usage is at least `minContextTokens` (default 200000; a nonnegative integer). It uses the configured classifier when available, otherwise the fresh verified summary; eligibility requires that classifier or a resolvable summary model. Classifier request failure may fall back to the verified summary, but expiry compaction never falls back to native Pi. Any failure to produce an accepted replacement cancels without a native-fallback diagnostic or warning. Pi cache warming extends the countdown. Unknown lifetimes, such as `openai-codex` in Pi's catalog, never trigger expiry compaction. Set `compactBeforeCacheExpiry: false` to disable this idle behavior independently of ordinary compaction. Its cost benefit has not been benchmarked; see [ADR 0045](../decisions/0045-compact-before-prompt-cache-expiry.md). Accepted classifier and summary compactions append bounded Pi-format ``/`` lists, merged with the latest compaction's file details, including previous Felan results. Expiry-triggered results record `trigger: 'cache-expiry'`. Info-level `session compaction request` logs include model, trigger, outcome, and latency; usage, cost, and `cacheShare` are included when available. `cacheShare` is the cache-read fraction of total input, rounded to three decimals. Classifier traces remain debug-level. For ordinary compaction, classifier split-prefix preparation failures go directly to native Pi, as do failures of the final fresh summary before Pi accepts a replacement. A failure after Pi accepts a replacement cannot automatically rerun native compaction. Every fallback to native Pi warns that it will take over and writes one bounded metadata-only diagnostic custom entry. The diagnostic is not shown, sent to the model, or returned by `session_recall`; it records delegation rather than native success. User cancellation is not reported as fallback. ### Terminal preferences The TUI owns `$FELAN_AGENT_DIR/tui/settings.json`. Themes, keybindings, thinking visibility, tool display, image rendering, output padding, editor padding, ask-user and task/history presentation, Powerline rendering, autocomplete size, hardware cursor, terminal progress, clear-on-shrink, Mermaid, startup verbosity, scrollbar, copy-on-select, and wheel scrolling stay on the client. They never enter the session protocol or daemon configuration. Web and chat clients own their own display preferences. For example: ```json { "theme": "felan-light/felan-dark", "hideThinking": false, "toolDisplay": "grouped", "editorPadding": 1, "keybindings": { "app.model.select": "alt+m" } } ``` Until a preference is present in this file, the TUI reads its Felan 0.28.3 value from `settings.json` and, for keybindings, `keybindings.json`. The first write copies all effective legacy preferences into the client file. It never writes these preferences back to either legacy file. Explicit launch theme/keybinding overrides remain active without changing saved defaults. Invalid legacy fields are skipped with one notice; other valid fields remain available and can be saved. Invalid values in the client file must be corrected before saving. Writes re-read the current file, merge only the edited fields, and atomically replace and sync the file and its parent directory. Editor padding defaults to one cell; output padding renders as zero when set to `0`, otherwise one cell, matching 0.28.3. The current TUI uses the fullscreen layout. `/settings` edits display preferences immediately and saves them locally; execution defaults apply to new sessions or an explicit `/reload`. Model and thinking changes for an attached session remain daemon session state. Persistent changes use the host configuration provider. `config.get` reports `writable` for the requested scope; a read-only host hides persistent save controls while session selection and local display remain usable. The local provider supports global writes, not project writes. No cloud provider is included. The dependency manager stores its revisioned onboarding manifest under `felanTui.onboarding`. It is internal state; prefer `/dependencies` over editing it directly. During interactive startup, before the login prompt, missing managed installers appear in one checklist with recommended items preselected; submitting a checked item authorizes installation and unchecked items use their safe fallback. Escape leaves the current pass pending. Available and non-installable dependencies resolve without another prompt. A complete manifest prevents the onboarding manager from probing external dependencies during normal startup. The full resource view reports extensions as enabled, disabled, or setup required without probing them. ## Application prompt append `APPEND_SYSTEM.md` extends the Felan base prompt for every local session. It is read when a session is constructed. A missing or blank file adds nothing; an unexpected read error stops session construction. Project `APPEND_SYSTEM.md`, Pi `SYSTEM.md`, and other ambient prompt files are not loaded. Use project instructions for repository-specific guidance instead. ### Classifier model Select **Classifier model** in `/settings`, or set the global value directly: ```json { "felanClassifier": { "model": "openrouter/typesafe/jev-1.13" } } ``` The value is `auto` (also used when omitted) or an exact `provider/model-id`. Auto considers only authenticated classifier models from Pi's catalog. It prefers direct TypeSafe `jev-latest`, then OpenRouter `typesafe/jev-1.13`, then other Jev routes, then the first remaining available classifier in catalog order. This can include configured local or other provider classifier models; it does not probe models with inference requests. Pi owns credential resolution using Felan's auth store, `models.json`, runtime keys, and provider environment variables. For example, TypeSafe can use `TYPESAFE_API_KEY` and OpenRouter can use a stored API key or `OPENROUTER_API_KEY`. The classifier is separate from the main coding model. An unavailable explicit choice warns and uses Auto without rewriting the saved setting. No authenticated classifier, or failed catalog discovery, leaves normal feature fallbacks in place. Changes apply when the next root runtime is created, for example with a new session or restart; children inherit their root's selection. The picker supports search, Escape to cancel, and save-failure feedback without changing unrelated settings. Token usage comes from Pi. USD estimates use catalog pricing; absent pricing is unknown, not proof of free inference. Changing providers can change judgment quality and data destinations, so validate the selected model on your workflow. ### Explicit classifier and image tools `builtinExtensions.modelTools` defaults to `true`. Set it to `false` to remove both `classify` and `generate_images`; internal classifier-guided features keep their own settings. Tool availability is checked when each runtime is constructed, including root, ACP, and child sessions. Image discovery also retries at session start if no image model was available during construction. `classify` appears only when the host has a configured classifier, using the Auto or explicit model selection above. Its arguments are a JSON-object `state` and a nonempty `questions` map using the existing `choice`, `bool`, and `score` contracts. It returns answers, available probabilities/confidence, model identity, elapsed time, and reported usage. Explicit tool calls are outside the initial 2-second automatic-decision preflight. Judgments are advisory, not facts or authorization; the state is untrusted evidence, not executable instructions. `generate_images` appears only when Pi discovers an authenticated image model. Use `{ "action": "list" }` to see configured provider/model IDs. Generate with `action: "generate"`, explicit `provider` and `model`, a text `prompt`, and optional local `referencePaths`. Pi resolves credentials through the existing host auth store, `models.json`, runtime keys, and provider environment variables; there is no separate tool key or endpoint setting. A chat model alone does not enable image generation without an image provider. If initial discovery finds no models, the tool can appear at `session_start` after another extension registers an image provider. Discovery failures leave the tool unavailable without breaking the session. Restart or create a session after adding a capability. With the Codex extension enabled and `extensionConfig.codex.imageGeneration` set to its default `true`, the legacy Codex login, `/login openai-codex`, enables provider `openai-codex-images` with models `gpt-image-2` and `gpt-image-2.5`. The selected chat model does not need to use Codex. Signing in with ChatGPT on the `openai` provider does not enable these image models. Sessions restricted by `enabledModels` list no image models from any provider, because the scope contains only chat models. Codex image requests go to `https://chatgpt.com/backend-api/codex/images/generations`. Up to five reference images switch the request to `/images/edits` on the same backend. The background is opaque. Requests count against the ChatGPT plan's Codex usage, not OpenAI API billing. These models have no API price, so Felan reports returned token usage without USD cost accounting. Image calls recheck authenticated availability; a disappearing model fails rather than silently switching providers. Prompt/reference bytes go to that provider and may incur charges. Remote URLs, network shares, traversal segments, and tool-supplied credentials/headers are not accepted. Output images are signature/MIME/base64 checked and saved under session storage at `model-tools/images//.`, without reusing existing directories. Results include paths, image/text content, and real available usage. Errors omit raw provider responses and credentials. Missing prices remain unknown; partial classifier usage stays in tool details rather than fabricated full accounting records. Treat generated content as untrusted. See the [model-tools README](../../packages/ext-model-tools/README.md) for complete examples and storage/error behavior. Llama integration remains deferred. ### Classifier-guided subagents When an authenticated classifier model is available, the local host injects its optional provider-neutral classifier into root and child runtimes. In composed root turns, registered entry, discovery and eligible regular-thinking questions share one sanitized context snapshot, classifier call and 2-second preflight budget. Oversized requests may use existing transport batching. A late decision falls back to the existing guidance or current thinking level. Later workflow decisions are outside this budget; see [classifier lifecycle](../concepts/classifier-lifecycle.md). Only root sessions use it for routing. Before each user turn, the subagent extension asks whether the request needs broad discovery that the conversation does not already cover; at 0.65 or higher it adds guidance to delegate that discovery to `explore` children. It also picks the model tier for `Agent` calls whose definition does not pin a model. Prewalk uses the classifier to recommend entry and a capable high-effort planning profile, set exploration depth, recommend implementation requirements, and check completion. Implementation recommendations never override configured targetModel/targetThinking. Every decision is optional: without a classifier, or when a call fails, the model follows the persistent guidance and the configured defaults apply. The classifier state may leave the local process for the selected provider's configured endpoint. Routing state contains prompt and bounded session text, tool names with short inputs, and agent metadata. Memory triage sends bounded, redacted excerpts from staged target transcripts, not the existing wiki, to that endpoint. It keeps oversized excerpts in the inspect source and falls back to a full worker audit on classifier failure. Recognized credential patterns are redacted from shared evidence, but arbitrary secrets in prompts, transcripts, or wiki text cannot be detected reliably; do not include credentials in classifier-bound requests. Routing decisions are logged at debug level under the `subagent-routing`, `subagent-model`, and `prewalk-classifier` components without the request text. The `turn-classification` component records the shared validated answers and metadata. ### Dynamic thinking level When a classifier is available, Felan selects reasoning effort when a new agent run starts on cache-safe models. It considers the new request and bounded recent session evidence using OpenAI's or Anthropic's published effort-level guidance. It does not reclassify tool continuations or follow-ups queued within a run. Only supported `low`, `medium`, `high`, `xhigh`, and `max` levels are candidates. Failed, uncertain, aborted, or unavailable classification keeps the current level, and automatic changes do not update your saved default. To disable dynamic thinking while retaining the classifier for other features, set this in `$FELAN_AGENT_DIR/settings.json`: ```json { "felanThinking": { "dynamic": false } } ``` The setting defaults to enabled and takes effect when a runtime is created or recreated. An explicit thinking-level selection overrides automation for the rest of that session; the headless `--thinking` option and explicit child-agent thinking also bypass it. Prewalk temporarily owns its planning and implementation profiles instead: its automated changes do not permanently disable ordinary dynamic thinking, which resumes after restoration and ownership release. Only GPT-6 Astra, Sol, Luna, and GPT-6.1 Sol using official OpenAI `openai-responses` or `openai-codex-responses` with the Codex extension enabled, Anthropic models marked for mid-conversation effort by the installed Pi adapter, and the same Claude models through the [Claude Code extension](claude-code.md), which applies the change with Claude Code's per-turn effort, qualify. Other providers qualify only when an extension declares native thinking updates for the model. With an OpenAI API key, Pi sends history `configuration_update` items itself on `openai-responses`; the Codex extension adds them on `openai-codex-responses`. Both keep request-level effort fixed. Eligible Claude models use per-message `output_config` while retaining a fixed request-level effort. Other GPT models, Chat Completions, older Claude models, and other providers keep their existing thinking behavior. Prompt caching still depends on the provider's eligibility, prefix, and retention; check cached-token usage rather than assuming savings. Classification itself adds latency and may incur a separate provider charge. The shared Agent Core evidence builder caps text and excludes image data, raw thinking, and tool-result bodies; recognized secret patterns are redacted on a best-effort basis only. Savings accounting uses the same per-token price at every effort level, including for models enabled through an extension's native thinking updates. Only an automatic selection below the user's `high`, `xhigh`, or `max` baseline on a supported model with observed reasoning-token usage on its first assistant response yields a possible estimated saving only after the run settles without tool failures. It compares the actual billable output with a 5% heuristic estimate of additional reasoning tokens at the baseline, anchored to one public benchmark, using `high-effort-reasoning-5pct-heuristic-v2`; when available, it includes the classifier's cost. The baseline is the level before the first automatic change, not the previous automatic selection. No measurement is emitted without an automatic change, for effort at or above the baseline, below-`high` baselines, failed or aborted responses, or an estimate that does not exceed the known classifier cost. If the classifier cost is unavailable, the estimate excludes that overhead. Details and quality limitations: [dynamic thinking estimate](../benchmarks/dynamic-thinking-effort.md). This extrapolation is not validated for every model or effort pair and does not prove savings or equal task quality. ## Project instructions and skills At startup Agent Core reads at most one instruction file in the session cwd: 1. `AGENTS.md` 2. `CLAUDE.md` The progressive-context extension discovers the same filenames below the cwd when Felan Code reads files in nested directories. See [Context and memory](context-and-memory.md). Agent Skills are loaded only from: - `~/.agents/skills` - `/.agents/skills` ## Agent definitions Definitions are loaded from these locations, with project definitions taking precedence over user definitions and Felan-specific directories taking precedence over shared `.agents` directories in the same scope: ```text ~/.agents/agents/*.md $FELAN_AGENT_DIR/agents/*.md /.agents/agents/*.md /.felan/agents/*.md ``` See [Agents, tasks, and Prewalk](agents-tasks-and-prewalk.md) for the definition format and model-selection behavior. ## Feature-specific configuration ### Browser authorization `extensionConfig.browser.authorizationPolicy` controls Felan's local consent prompt when reusing an existing authenticated Chrome session. It defaults to `ask`, whose prompt offers Allow once, Always allow, or Deny. Set it to `always-allow` to skip Felan's repeated prompt. Authorization grants the native browser command surface, while Felan still owns routing, output bounds, lease lifecycles, and host setup commands. Set it back to `ask` in `/settings` or with `--browser-authorization-policy ask` to restore the default behavior. The preference is global to `$FELAN_AGENT_DIR`; live grants and CDP connection material are never persisted. Explicit CLI and programmatic overrides take precedence for the runtime. ### Prewalk Model-called `enter_prewalk` uses the resolved `extensionConfig.prewalk` settings. A dialog-capable host asks when configured `ask`; JSON and print modes deny the request instead of waiting for input. Explicit `/prewalk` is already user intent and bypasses this gate. The local `/settings` screen edits these values and persists them to `settings.json`. `entryApproval` accepts `ask`, `allow`, or `deny`. `planReview` accepts `inherit`, `ask`, or `skip`: `inherit` asks when `entryApproval` is `ask` and skips otherwise. The example above uses the unattended policy explicitly, so model entry is allowed and plan review is skipped. CLI session overrides use a generic JSON object, validated by the host against the enabled extension declarations. For example: ```sh felan --prewalk-entry-approval allow --prewalk-plan-review skip ``` The precedence is defaults, then `settings.json`, then CLI invocation values. Agent Core consumers can supply a final programmatic override with `configureExtension()` and `extensionConfigOverrides`. Invalid persisted extension fields do not block local startup. Felan Code reports a warning, ignores each invalid field, and uses that field's declared default; other valid fields in the same extension remain active. Invalid CLI and programmatic overrides remain errors. Felan Code does not rewrite invalid persisted values automatically. ### Tasks The TUI owns `presentation.tasks.displayMode` in `tui/settings.json` (`inline` or `overlay`). Change it in `/settings` or use `--tasks-display-mode overlay` as a launch override. This does not change task execution or the daemon. ### Context View The `extensionConfig.contextView.displayMode` setting controls `/context` in the interactive TUI. It defaults to `inline`, which replaces the current content with the report until it is closed. Set it to `overlay` for a centered popup. Headless modes always emit the compact report as text output. Inline output uses two horizontal separators; overlay output uses a complete four-edge frame. The report attributes the initial memory `summary.md`, `index.md`, and schema to Memory, along with identifiable reads from the session memory projection; ordinary conversation messages remain under Messages. ### Prompt History The TUI owns `presentation.promptHistory.displayMode` in `tui/settings.json`. The default is `inline`; select `overlay` in `/settings` or use `--prompt-history-display-mode overlay` for this launch. ### Ask User The TUI owns `presentation.askUser` in `tui/settings.json`: ```json { "presentation": { "askUser": { "displayMode": "inline", "singleSelectLayout": "auto", "overlayToggleKey": "alt+o", "commentToggleKey": "ctrl+g" } } } ``` Edit these preferences in `/settings` or use the corresponding `--ask-user-*` launch flags. Per-call `ask_user` presentation hints remain in the tool contract; clients may ignore them. The generic form adapter ignores them. ### Output style The `extensionConfig.outputStyle.style` setting accepts `concise`, `explanatory`, or `custom`. `concise` is the default. It uses short sentences, clear fragments, compact bullets, standard abbreviations, and minimal prose, but expands when compression could cause ambiguity around errors, security, destructive actions, blockers, limitations, recovery, tradeoffs, or complex plans. Technical terms, code, commands, paths, identifiers, API names, numbers, units, and exact error messages remain unchanged. Negation, conditions, scope, exceptions, caveats, verification results, and blockers are not omitted. The output-style extension appends the selected instructions as a bounded `## Output Style` section for root and child sessions. Use `custom` to supply arbitrary system-prompt instructions without changing the extension source. Provide exactly one of inline `instructions` or `instructionsFile`: ```json { "extensionConfig": { "outputStyle": { "style": "custom", "instructions": "Respond tersely. Keep all technical details and blockers." } } } ``` ```json { "extensionConfig": { "outputStyle": { "style": "custom", "instructionsFile": "output-style.md" } } } ``` Relative `instructionsFile` paths resolve from `$FELAN_AGENT_DIR`. Absolute paths are used as written. Paths starting with `~/` expand to the current home directory. The local host reads the file when it binds the extension for root and child sessions; empty, missing, or unreadable files are errors. Setting both `instructions` and `instructionsFile` is an error. The same values can be selected in `/settings` or with generic session overrides: `--output-style concise`. For custom output, use the `instructions` or `instructionsFile` fields in the same object. The former `caveman` value has been replaced by `concise`. Existing configurations should change either legacy `"outputStyle": "caveman"` or `extensionConfig.outputStyle.style: caveman` to `concise`. Invalid persisted namespaced values produce a warning and use the concise default; invalid CLI or programmatic values are errors. Felan Code does not retain `caveman` as an alias. The local host captures the selection and instruction-file contents when it creates a session runtime, so restart Felan Code after changing the style or the file. Set `builtinExtensions.outputStyle` to `false` to disable the extension. ### Codex tools `extensionConfig.codex` accepts these fields: ```json { "verbosity": "low", "forceCachedWebSockets": true, "postAgentRunCompaction": true, "imageGeneration": true } ``` `verbosity` may be `low`, `medium`, or `high`. Chat request controls apply only to eligible GPT models on the exact `openai` or `openai-codex` provider. `imageGeneration` defaults to `true` and registers the separate `openai-codex-images` provider when the host supplies the Models service. Set it to `false` to disable these image models without changing Codex chat behavior. Changes apply to new sessions or after a restart; `/reload` keeps a provider the session already registered. See [image tools](#explicit-classifier-and-image-tools) for login and usage. Optionally add `"priority": "normal"`, `"fast"`, or `"ultrafast"` to this Codex configuration. Explicit priority overrides `fast`; omitting it preserves the existing boolean behavior. The `fast` boolean is deprecated and hidden from `/settings`, but remains supported in existing config files and CLI options. With both omitted, no premium tier is requested. `normal` requests the standard tier even if `fast` is true. `ultrafast` requests Ultrafast for the exact `gpt-6-astra` and `gpt-6.1-sol` IDs on eligible Responses routes and falls back to fast for other eligible GPT models. This capability rule is maintained in the extension because Pi does not expose service-tier metadata. Account and workspace access requirements still apply; entitlement errors are not automatically retried. Neither reasoning effort nor transport changes. Fast and Ultrafast use premium quota/pricing; 2x/8x are not universal billing rates or guaranteed task-speed improvements. See [OpenAI's speed documentation](https://learn.chatgpt.com/docs/agent-configuration/speed). Pi's cost estimates do not currently account for Ultrafast-specific pricing. `postAgentRunCompaction` defaults to `true`, making automatic threshold compaction wait until the active GPT run settles and preserving the pre-0.84.4 timing. Set it to `false` to use Pi's standard timing. Manual and overflow-recovery compaction are unchanged. Pi continues to generate the compaction summary; this is not OpenAI native Responses compaction. On GPT-6 Astra, Sol, Luna, and GPT-6.1 Sol with `openai-responses` and an OpenAI API key, Pi sends `configuration_update` items itself, keeping request-level `reasoning.effort` fixed at `medium`. For `openai-codex-responses` on either eligible provider, the Codex extension persists updates before the next user message while keeping the initial request-level effort unchanged. Both paths can preserve the prompt cache across level changes and session resume. Older `openai`/`openai-responses` sessions ignore persisted `codex-reasoning-update` entries and resume at Pi's fixed `medium` request effort, so expect one prompt-cache miss if their original initial effort was not `medium`. Extension updates require standard, single-agent Responses requests; pro mode, server-side multi-agent mode, Chat Completions, other models, and Anthropic are not supported. A queued user follow-up can receive an update at its next safe turn boundary. Changes during a tool continuation remain deferred until a new user turn or the run settles. Pi compaction starts a new prefix, and automatic server compaction or truncation is incompatible with these updates. Verify actual reuse from the provider's cached-token usage. `forceCachedWebSockets` still applies only to `openai-codex` / `openai-codex-responses`. Reasoning updates on the official OpenAI API do not change its native Pi transport. GPT models keep Felan Code's ordinary `read` and `bash` tools. Codex mode replaces only `edit` and `write` with `apply_patch`; process sessions and image reading are not provider-specific. ### Claude Code provider `builtinExtensions.claudeCode` enables the built-in, but models register only when the managed Agent SDK is installed on a supported host. Run `/claude-code install`, then start a new session or reload. Claude Code login is separate from Felan provider credentials: run `claude`, then `/login`, on the machine running the daemon. Use `/settings` or `extensionConfig["claude-code"]` for these fields: | Field | Default | Meaning | | --- | --- | --- | | `plan` | `"pro"` | `"pro"` or `"max"`; selects plan-gated context windows, not authentication. | | `longContextExtraUsage` | `false` | Allow long-context variants that may consume paid Extra Usage. | | `forceTwoHundredK` | `[]` | Array of model IDs limited to 200K context, without `claude-code/` or `[1m]`. | | `strictMcpConfig` | `true` | Ignore local Claude Code MCP configuration and use Felan's tools. Claude.ai-connected MCP servers remain disabled. | | `autoMemoryEnabled` | `false` | Enable Claude Code auto-memory in addition to Felan memory. | | `pathToClaudeCodeExecutable` | unset | Optional absolute path to `claude` instead of the SDK-bundled binary. | | `inheritAnthropicEnvironment` | `false` | Preserve exported `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, and `ANTHROPIC_BASE_URL` in the child; otherwise remove them to use Claude plan login. | Unknown fields and invalid values are rejected. Settings apply on activation in a new session or reload; the bridge uses process-wide settings, so the latest activation governs subsequent queries in a shared daemon. Environment inheritance can change authentication, destination, and billing. Zero model prices in Felan do not mean free usage or guaranteed plan eligibility. See the [Claude Code guide](claude-code.md) for setup, compatibility, privacy, long-context behavior, and troubleshooting. ### Background processes `extensionConfig.backgroundBash.foregroundTimeoutSeconds` controls how long a non-PTY foreground `bash` call waits before promotion. It defaults to `120` seconds. Foreground commands run as in-process children through `runtime.processes.startShell` without a job record. They return the last 2000 lines / 50 KB of output. Larger output spills in full to `/background-bash//output/output-*.log`; the newest 20 spill files are kept. A command that outlives a positive timeout becomes an attached background job without restarting. It gets a record with `executionMode: 'attached'`, an `output.log`, and completion messages, and appears in `list_background_bash` and `/processes`. It stops when the session that started it closes or reloads (a subagent's attached jobs end with that subagent), records `killed` when stopped, and is never reattached. Cancelling a turn does not stop it. The daemon still tracks the child as a `foreground` process, so the TUI footer does not count it. Attached jobs have no stdin. For non-PTY commands, setting `background: true` or a timeout of `0` starts a detached job immediately. Detached records remain discoverable after restart when session storage persists. `tty: true` starts a PTY with a job record from the start, and `write_background_bash` sends exact input/control bytes. Live PTYs end with the root session. Use `tty: true` when interactive input is needed. ### Web access `extensionConfig.webAccess` exposes provider selection, OpenAI/Exa/Brave credential sources, the OpenAI search model, SearXNG endpoint and sensitive headers, PDF size limit, `fetchContent.domainPolicy`, and `ssrf.allowRanges`. Credential sources and SearXNG headers are redacted in settings presentation. The removed `githubClone` field is not available. Search provider requests can consume quotas or incur provider charges, especially with `all` or an array. Use `web_search` for discovery, then pass selected URLs to `fetch_content`. See [Web, MCP, browser, and documents](web-mcp-and-browser.md) for the full schema, limits, and migration guidance. ### MCP `mcp.json` is global to the agent directory. `/.mcp.json` overrides same-name global servers. The local host accepts remote HTTP OAuth servers only; unsupported stdio, socket, bearer-token, and custom-header entries are skipped. ### Felan API The `felanApi` built-in registers the single `felan_api` gateway only when `FELAN_API_KEY` is set. Set `builtinExtensions.felanApi` to `false` to disable it. The gateway uses `FELAN_API_URL` when set, otherwise the production Felan API, `FELAN_DOCS_URL` for the optional public documentation target, and `FELAN_TEAM_SLUG` as guidance for team-scoped paths. It keeps responses bounded and marked as untrusted. A managed host can compose `@felan-ai/ext-felan-api` with explicit `apiKey` and `teamSlug` values instead of using the environment. ### Powerline Powerline separates collected data from TUI rendering. Host behavior settings remain under `extensionConfig.powerline` in `settings.json`: ```json { "showWorkingTree": true, "showStashCount": false, "periodDays": 7, "maxWindows": 3 } ``` The TUI owns `presentation.powerline` in `tui/settings.json`: `style` (`minimal`, `powerline`, `capsule`), `charset` (`text`, `unicode`), `autoWrap`, `padding`, and ordered `lines`. Each line contains `segments`; a segment has `enabled`, optional `align` (`left` or `right`), optional `colorKey`, and display options such as directory `style`, session `type`, or subscription `showReset`. Data-collection options do not belong in this layout. The default is a three-line minimal text footer, with padding 1 and wrapping enabled. The third line appears only when extension statuses exist; the default layout has no version segment. External Git changes appear on the next extension event or within the 60-second cache refresh, rather than immediately through a client-side branch watcher. Use `/settings` or the TUI-only `--powerline-style`, `--powerline-charset`, `--powerline-auto-wrap`, `--powerline-padding`, and `--powerline-lines` flags. They never reach the daemon. Disable the extension with `builtinExtensions.powerline: false` to stop collection and publication. The `felan.powerline@3.0.0` hint carries structured values and semantic color roles, not rendered text or terminal layout. ACP and headless clients retain the generic plain-data fallback. Collection and publication do not require a TUI attachment. ### Extension configuration Execution flags such as `--codex-priority ultrafast`, `--codex-fast`, `--no-codex-fast`, `--codex-verbosity low`, `--fusion-thinking high` and `--fusion-participants '["openai/model-a","anthropic/model-b"]'` are generated from built-in extension definitions. They set session overrides in interactive and headless (`--mode text|json`) launches; they never persist defaults. ACP accepts no extension flags, matching 0.28.3. `--extension-config` is not supported. Display flags remain TUI-only, including their 0.28.3 names and value syntax. Until a TUI preference is saved, the TUI reads the corresponding released `extensionConfig..` value from `settings.json` without writing it. Saved local values take precedence per field. Other clients keep their own presentation preferences. Every enabled configurable extension declares typed settings. Felan Code exposes the same declarations through `settings.json`, generated per-field CLI flags, `/settings`, and the Agent Core programmatic API. Values are validated before activation; unknown extension or field names are errors. `/settings` first lists Pi settings and configurable extensions; select an extension to view its fields. Type to fuzzy-search either list; activating a field with declared options cycles them. ### RTK Use `/settings` to edit `extensionConfig.rtkOptimizer`. `/rtk` shows operational status, verifies availability, and installs the reviewed executable. `/savings` reports Felan Code's estimated API-equivalent savings. Command rewriting needs the reviewed `rtk` executable; binary-independent output compaction does not. Felan Code's post-tool metrics include command, read, grep, and Codex result compaction (including non-RTK compaction), and RTK command-output savings are reported separately from Felan Code's post-tool compaction. Felan Code uses one isolated temporary RTK tracker per root session and model, queries each tracker during session shutdown, and never imports RTK's global history or exposes `rtk gain`. Active-session `/savings` may not yet include unflushed RTK command-output savings. These are API-equivalent estimates, not provider billing; see [Efficient execution and savings](../concepts/efficient-execution.md). Large lossy results use a recoverable head-and-tail preview; failed results and complete JSON payloads are protected from false-success or mid-document cuts. ### Codebase Memory `extensionConfig.codebaseMemory.maxCacheBytes` is a non-negative integer. The default `0` selects the runtime policy: 2 GiB for the local host and 500 MiB for Docker or Daytona. A positive value overrides that limit. Codebase Memory uses agent-scoped cache storage on the local host and session-scoped storage in cloud workspaces, starts one background index without delaying session startup, and refreshes only after `/codebase-memory refresh` or a model `index_repository` request; it does not watch files. Set the optional `extensionConfig.codebaseMemory.autoIndexPath` to an absolute directory when a host should index an aggregate such as `/work/repos` instead of its Git root. Daemon coordination is derived from the agent-storage root and uses a bounded owner-private temporary path on POSIX so Unix socket paths remain portable. The exact reviewed 0.11.0 executable is required. Use `/dependencies` or `/codebase-memory install` for an explicit local install. Known fatal daemon-coordination failures are recovered by participating current sessions through a bounded graceful daemon stop and one index retry. Restart Felan Code once after upgrading so existing sessions load this recovery behavior. ## Secrets Use `/login` to add model credentials and `/logout` to remove them. Use `/mcp` for remote MCP OAuth credentials. The local MCP host stores OAuth tokens in the OS credential store and fails closed when secure storage is unavailable. Prefer environment references over literal client secrets when an MCP server requires a registered client. Never commit `$FELAN_AGENT_DIR`, credential files, or private provider keys.