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 GitHub account with access to the Faber repository.
• A Claude subscription is the simplest builder path, though Codex sign-in, API providers, and local OpenAI-compatible servers are also supported.
• Git, GitHub CLI, Python, and a terminal; the installer prepares the environment.

Install Faber

Choose the command block for your operating system. 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"

sudo apt update && sudo apt install -y git gh python3 python3-venv python3-pip
curl -fsSL https://claude.ai/install.sh | bash
gh auth login && gh repo clone bennidao/Faber ~/Faber && bash ~/Faber/scripts/install.sh

sudo dnf install -y git gh python3 python3-pip
curl -fsSL https://claude.ai/install.sh | bash
gh auth login && gh repo clone bennidao/Faber ~/Faber && bash ~/Faber/scripts/install.sh

brew install git gh python
curl -fsSL https://claude.ai/install.sh | bash
gh auth login && gh repo clone bennidao/Faber ~/Faber && bash ~/Faber/scripts/install.sh

The installer signs into GitHub, creates the Python environment, installs dependencies, writes a working .env, and prepares the local database.

Give any LLM this install prompt

Copy this prompt into the LLM you are using. It tells the model to identify your operating system, keep you in control of sign-in, and stop if an account or permission is required.

Help me install Faber on this computer. First, tell me whether you need Windows, macOS, or Linux details; if you can detect the OS, state it and proceed.

Rules:
- Explain each command before I run it and wait for me at account-login, browser-authorization, firewall, or permission prompts.
- Do not ask me to paste passwords, API keys, or tokens.
- Faber is a local-first app. Keep its data and keys local.
- I need GitHub access to bennidao/Faber and a terminal. Claude subscription login is the default builder route, but mention Codex sign-in or local/API providers as alternatives.

Windows (PowerShell):
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"
cd "$env:USERPROFILE\Faber"
.\scripts\run.ps1

Ubuntu / Debian:
sudo apt update && sudo apt install -y git gh python3 python3-venv python3-pip
curl -fsSL https://claude.ai/install.sh | bash
gh auth login && gh repo clone bennidao/Faber ~/Faber && bash ~/Faber/scripts/install.sh
cd ~/Faber && ./scripts/run.sh

Fedora:
sudo dnf install -y git gh python3 python3-pip
curl -fsSL https://claude.ai/install.sh | bash
gh auth login && gh repo clone bennidao/Faber ~/Faber && bash ~/Faber/scripts/install.sh
cd ~/Faber && ./scripts/run.sh

macOS:
brew install git gh python
curl -fsSL https://claude.ai/install.sh | bash
gh auth login && gh repo clone bennidao/Faber ~/Faber && bash ~/Faber/scripts/install.sh
cd ~/Faber && ./scripts/run.sh

After installation, guide me through claude login if I am using a Claude subscription. Remind me not to set ANTHROPIC_API_KEY when I want subscription authentication. Then direct 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

Use the launcher. It owns logs, update checks, and crash recovery.

.\scripts\run.ps1

./scripts/run.sh

When startup completes, open http://localhost:8088. Keep the launcher 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.

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.