Work with Faber

What's inside

Faber is more than a chat window connected to a coding model. It is a durable workspace with a working agreement around the agent.

What you'll need

• A Windows machine and PowerShell.
• A GitHub account with access to the Faber repository.
• A Claude subscription — the simplest builder path. Codex sign-in, API providers, and local OpenAI-compatible servers also work, and are covered in Bring your own models.
• Git, GitHub CLI and Python; the installer prepares the environment for you.

Install Faber

Run these in PowerShell, in order. The installer is safe to rerun when you update or repair an installation.

winget install --id GitHub.cli -e --source winget
gh auth login
gh repo clone bennidao/Faber "$env:USERPROFILE\Faber"
& "$env:USERPROFILE\Faber\scripts\install.ps1"

The installer signs into GitHub, creates the Python environment, installs dependencies, writes a working .env, and prepares the local database. Faber lands in %USERPROFILE%\Faber.

Rather have an LLM walk you through it

If you would rather be talked through the install than run the commands yourself, paste this into Claude. It tells the model to explain each step before you run it and to stop wherever you need to sign in.

Help me install Faber on this Windows computer. Explain each command before I run it, and wait for me at any sign-in, browser-authorization, or permission prompt. Do not ask me to paste passwords, API keys, or tokens - Faber is local-first and my keys stay on this machine.

I need a GitHub account with access to bennidao/Faber, and a Claude subscription for the builder.

Run in PowerShell:
winget install --id GitHub.cli -e --source winget
gh auth login
gh repo clone bennidao/Faber "$env:USERPROFILEFaber"
& "$env:USERPROFILEFaberscriptsinstall.ps1"
cd "$env:USERPROFILEFaber"
.scripts
un.ps1

Then walk me through claude login. Remind me NOT to set ANTHROPIC_API_KEY - it overrides subscription auth and bills API credits. Finally, send me to http://localhost:8088 and help me create my first project.

Sign the agent in

The default builder uses your Claude subscription. Sign in once:

claude login

For Codex, run codex login and choose the Codex sign-in route in Settings. API and local-provider setup is covered in Bring your own models.

First run

Start Faber through the launcher. It owns logs, update checks, and crash recovery, and a watchdog restarts the server if it dies.

cd "$env:USERPROFILE\Faber"
.\scripts\run.ps1

When startup completes, open http://localhost:8088. Keep the launcher window open while Faber is running; Settings provides a clean restart and quit flow.

Projects and sessions

A project is the home for one piece of work. It owns its folder, sessions, tickets, decisions, files, and memory.

• Create a project from the sidebar; Faber scopes its working records to that project.
• Use sessions for separate conversations inside the project. Past sessions replay after refresh or restart.
• Search finds prior sessions and durable project decisions without leaking context from another project.

How a turn works

• A "What I heard" card restates the outcome, constraints, and any real unknowns before the builder proceeds.
• A live Working card exposes progress; the technical stream remains available under the hood.
• Before the partner report, Faber checks the work against its standards. Long work can hand off with a written recap when context fills.
• You can keep typing while it works. New input is carried into the work safely rather than lost in chat history.

Ticket board and automatic flow

Tickets make scope, dependencies, evidence, and acceptance criteria visible. The normal rhythm is one focused ticket per turn, then the next ready item only after the first has real proof.

• Add, edit, defer with a reason, or cancel obsolete work; partial work is not silently called complete.
• Dependencies hold later work until prerequisites are actually verified.
• If a result still needs a restart, flag, or go-live action, Faber creates a separate activation ticket so built is not confused with live.

How a ticket earns “done”

An agent saying it finished is a claim, not a result. Every ticket with acceptance criteria is checked against them by an independent verifier before it can close.

The criteria are captured when the ticket is created and shown on the card, so what “done” means is agreed before the work starts rather than argued afterwards. When the builder says it is finished, a separate pass reads the criteria one at a time and records its own verdict on the ticket.

Until that verdict passes, the ticket's completion is provisional — the done state, the commit it points at, and its summary are all held. The card carries a PASS, FAIL or UNVERIFIED chip so you can see which tickets are genuinely finished at a glance.

It fails toward caution, not convenience

• If the verifier itself is unavailable, the ticket reads UNVERIFIED rather than passing by default. An outage cannot quietly close work.
• A ticket for code will not close on a documentation-only commit. The claim has to match what actually changed.
• Tickets with no acceptance criteria are skipped rather than blocked — the gate applies where there is something to check.

When you need to close it anyway

Sometimes the verifier is wrong, or the criteria were written badly. Override & close appears on a ticket the gate is holding, and it is the only path that bypasses verification. It requires a written rationale, which is recorded on the ticket — and once overridden, the reconciler will never quietly re-verify, downgrade, or reopen it.

Decisions and approvals

At a consequential fork, Faber stops for a decision card with options and trade-offs. Your choice becomes a durable project constraint.

• Risky operations such as destructive deletes, force pushes, and database drops require the configured level of approval.
• Autonomous mode keeps risky actions blocked; Guarded asks at meaningful boundaries; more restrictive settings ask more often.

Review, fixes, and reliability

Audit cards show findings with severity, category, explanation, and the related ticket. Send a valid finding back to the builder for a focused repair, or dismiss it with a reason when it does not apply.

Settings exposes auditor reliability so you can distinguish recurring real failures from review noise. The system records the evidence behind each conclusion.

Side Chat

• Side Chat reads the active project's map, relevant history, decisions, reference material, and ticket board for quick questions.
• It is deliberately read-only: it cannot run commands, change files, or begin a build.
• Copy an answer, or use it as a drafted prompt in the main composer. Ticket suggestions require your explicit Add to board action.

Faber Brain and privacy

The Brain is a read-only, searchable bundle of synthesized, cross-project knowledge. Within a project, the Context Map says where detail belongs so new turns can start informed without loading everything.

It learns your methods

When you repeat a kind of work, Faber can offer to capture the rules, numbers, and finished shape that make up your method. Your answers form a reusable skill; decline it and Faber will not keep asking about that task type.

Files and previews

• Preview spreadsheets, documents, PDFs, images, code, and supported HTML directly beside the chat.
• Choose full-width or split layout, and follow document links within the preview.
• The project file browser stays tied to the active project.

App Browser

• Register a local app once with its command and port; builder-created apps can register themselves.
• Start and stop supervised apps from their tab. Faber distinguishes running, starting, stopped, and a port owned by another process.
• Tabs persist per project. If an app blocks iframe embedding, use Browser to open it normally.

Faber on your phone

Enable remote access, restart while no work is running, then scan the generated QR code on the same Wi-Fi network. The phone layout keeps chat full-width and puts sessions behind the menu.

Voice and access from anywhere

Tailscale can provide authenticated HTTPS access from outside your home network. That HTTPS route also enables browser microphone access for phone dictation. On a shared tailnet, review access controls before exposing the instance to additional people.

Plugins for Codex and Claude

Faber's ticket, evidence, and audit contract also ships as a local plugin for coding-agent CLIs. A ticket becomes verified only by a recorded audit verdict, never a model's self-assigned status.

codex plugin marketplace add bennidao/Faber_For_Codex
codex plugin add faber-for-codex@faber-for-codex

/plugin marketplace add bennidao/Faber_For_Claude
/plugin install faber-for-claude@faber-for-claude

Start a fresh CLI session after installation. The local board is project-scoped today; it does not synchronize across machines yet.

Version and sync

Settings shows whether Faber is in sync, has an update available, or has local changes that need backup. Install update pulls and restarts safely; a diverged copy can be reset after a recoverable backup is made.

Your projects, not just Faber

Every project can back up to GitHub, pull changes, reset to match GitHub, initialize version control, or connect an existing empty remote. Faber keeps project backup separate from its own application updates.

Settings worth knowing

• Version and sync handles updates, backup, restart, and quit.
• Startup can launch Faber at login where supported.
• Header controls keep the selected model and permission level available.
• Usage shows recent model consumption; model routing configures the builder and helper fallbacks independently.

Bring your own models

The default Claude subscription is not a requirement. Builder and helper roles can use Codex ChatGPT sign-in, an OpenAI API key, OpenRouter or another compatible provider, or a local OpenAI-compatible server such as LM Studio, llama.cpp, vLLM, or Ollama.

Each helper role has a fallback chain and a test control. Keys stay in local environment configuration, not the database or UI.

Troubleshooting

• A fix seems missing: refresh first, then use Settings -> Restart server.
• Port already in use: an older Faber process is still running; close it or reboot before starting again.
• Startup hangs: inspect logs/last-crash.txt and logs/server.err.log.
• Update diverged: use Version and sync -> Reset to match GitHub; it saves a recoverable backup first.
• Phone or microphone fails: check network, Tailscale, HTTPS, and tailnet access controls.