FAM_OS

For All Mankind Operating System

A local-first AI agent that can understand a workspace, use Linux tools, edit real projects, and keep working until the result is verified.

Explore the FAM_OS project site

Built by Ivan Dimitrov

---

FAM_OS is an agent runtime built above Linux. It gives local models or an authenticated Codex agent persistent task context, real tools, durable long-running goals, isolated engineering workspaces, and evidence-based verification.

It is designed to feel closer to Codex, Claude Code, or Windsurf than to a one-shot chatbot, while keeping inference and execution on the owner's machine.

User objective
  -> adaptive agent harness
  -> relevant tools and compact working context
  -> observe / edit / execute / recover
  -> verify declared completion criteria
  -> apply the accepted candidate to the selected workspace

FAM_OS does not replace the Linux kernel and does not require every selected folder to be a Git repository. Ordinary filesystem tasks use direct, task-scaled operations. Repository engineering uses Git only when repository semantics are actually needed.

Goal Mode working through a local engineering task with live tool evidence, candidate isolation, progress telemetry, and recovery controls.

What works today

• Conversational workspace assistance. Follow-up requests retain the objective, recent decisions, relevant observations, changed files, and unresolved errors instead of treating every prompt as a new conversation.
• Adaptive local tool use. The model starts with the smallest relevant tool set and can request more capabilities as the task develops.
• Real filesystem and command execution. The agent can inspect folders, read and write files, create directories, run project commands, and verify their effects.
• Stateful application testing. An Application test profile can launch or attach to localhost web apps, interact through structured Playwright snapshots, retain console/network evidence, assert outcomes, and capture screenshots, traces, and videos.
• Task-scaled execution. A simple file operation does not enter a heavyweight repository workflow. Larger engineering work receives planning, mutation, and verification phases.
• Isolated candidate workspaces. Engineering changes are built away from the owner's folder. The Console shows created, modified, and deleted paths while the goal runs; verified work is reconciled into the real workspace at the end.
• Durable Goal Mode. A reviewed plan can continue in the background across many model/tool steps. Goals support pause, resume, guidance, cancellation, checkpoints, elapsed time, progress signals, and completion criteria.
• Automatic recovery. Transient model disconnections, timeouts, unloading, and stalled requests enter retry_wait, run provider health/recovery checks, and resume from the same durable checkpoint and candidate workspace. Confirmed filesystem effects are not blindly repeated.
• Compact evidence. Tool output is summarized and bounded before it returns to a local model; retained observations are compacted around the objective and current work.
• Local model routing. General and engineering work can use different Ollama models. The current workstation configuration has been exercised with qwen3.8:27b for engineering work.
• Native Codex engineering. An optional ChatGPT-authenticated Codex provider can inspect, edit, run, test, and self-correct directly inside the isolated candidate while FAM retains verification and final delivery.
• Authenticated local Console. The browser UI exposes workspace selection, conversation, tool evidence, candidate changes, Goal Mode controls, recovery state, and machine status.
• First-class Omarchy 4 integration. FAM_OS ships a signed x86_64 Arch package, unprivileged systemd user lifecycle, UWSM/Hyprland adapters, an independently signed fam.os Quickshell plugin, native and browser application testing, compatibility usage telemetry, snapshot-aware system goals, and doctor/repair commands. aarch64 is experimental and Omarchy 3 is unsupported.

How the agent loop works

For an ordinary request, FAM_OS selects a task-sized path:

1. Preserve the conversation objective and select the relevant workspace context.
2. Expose only the tools likely to help with the current step.
3. Let the model observe, reason, and call tools iteratively.
4. Return small semantic results such as exists=true, the resulting path, changed hashes, or command status.
5. Repair malformed calls or recover from transient failures without discarding useful progress.
6. Verify the requested outcome and report what actually happened.

For Goal Mode, the lifecycle is longer:

1. Prepare: create a plan and explicit completion checks for owner review.
2. Build: copy the selected workspace into an isolated candidate and let the agent work there.
3. Verify: evaluate every completion criterion against the candidate using real file and command evidence.
4. Apply: reconcile the verified candidate into the owner's workspace, then check the applied result.

The original folder remains unchanged while Build and Verify are running. If a goal pauses, the service restarts, or the model temporarily disappears, the durable goal record and candidate are preserved.

Install on Omarchy

After inclusion in the Omarchy package repository:

omarchy pkg add fam-os
fam-os setup omarchy --yes --enable-widget

Before repository inclusion, inspect the FAM-owned release installer. It confirms Omarchy 4/x86_64 and disk space, verifies the pinned signing key, signed checksum manifest, package checksum and detached package signature, then installs with pacman:

curl -fsSL https://raw.githubusercontent.com/demimagic-ML/FAM-os/main/packaging/omarchy/bootstrap.sh | less
curl -fsSL https://raw.githubusercontent.com/demimagic-ML/FAM-os/main/packaging/omarchy/bootstrap.sh | bash

Open FAM or submit work directly from a project:

fam                       # interactive terminal session
fam chat                  # same interactive chat surface
fam goal                  # interactive session starting in Goal Mode
fam "Explain this project and run its tests"
fam goal "Finish this application, test it, and verify the build"
fam console
omarchy-fam --interactive
omarchy-fam --prompt "Review this project"

FAM is an agent supervisor rather than a direct replacement for one provider: it selects and supervises Codex or a configured local engineering model while retaining the durable objective, candidate workspace, tool evidence, recovery state and verification record across terminal, widget and Console surfaces.

Setup is idempotent and uses Omarchy's Git-plugin, menu-extension and post-update-hook lifecycles; it does not make manual QML copies, edit systemd/Hyprland configuration, or embed owner-specific paths. The focused upstream Omarchy contribution adds omarchy default agent fam, interactive scratchpad launches and prompt/crash routing; until that PR is merged, the packaged omarchy-fam command provides the same FAM-side contracts. See the complete Omarchy installation guide.

Run the current development service

Prerequisites

• Linux with Python 3.12 or newer
• an existing development environment at .verification-venv
• Ollama listening locally (the command below expects port 11435)
• the configured model already pulled into Ollama

From the repository root, choose state and runtime locations using the standard XDG directories:

export FAM_STATE_ROOT="${XDG_DATA_HOME:-$HOME/.local/share}/fam-os"
export FAM_RUNTIME_ROOT="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/fam-os-adaptive-agent"

PYTHONPATH=src .verification-venv/bin/python -m fam_os.product.service \
  --state-root "$FAM_STATE_ROOT" \
  --runtime-root "$FAM_RUNTIME_ROOT" \
  --model qwen3.8:27b \
  --engineering-model qwen3.8:27b \
  --ollama-url http://127.0.0.1:11435 \
  --external-ollama \
  --console-port 8775

Keep that process running. In a second terminal, verify both services:

ss -ltnp | rg ':8775|:11435'
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8775/

Open a fresh authenticated Console session from another terminal:

PYTHONPATH=src .verification-venv/bin/python -c \
  'import os; from pathlib import Path; from fam_os.product.console_cli import run_console_command; raise SystemExit(run_console_command(Path(os.environ["FAM_RUNTIME_ROOT"]), 8775))'

The launcher opens a tokenized local URL. A bookmarked Console URL can expire; run the launcher again instead of reusing an old token.

Installed builds use the fam-service, fam-os, and fam-console entry points declared in pyproject.toml.

Try it

Choose a workspace with Open folder, select Use folder, and start with bounded tasks:

Explain this project and identify its real test and build commands.

Inside reports, create alpha.txt, beta.txt, and gamma.txt containing
ALPHA, BETA, and GAMMA respectively. Verify all three files.

Then test conversation continuity:

Create a concrete improvement plan for this project.

Implement the plan, run the relevant tests, and summarize the changed files.

For a larger task, enable Goal mode, submit an outcome such as:

Plan and fully implement a browser-based Snake game in this folder.
Verify that it builds, that its tests pass, and that the game can be started.

Review the proposed plan and completion criteria before activation. While it runs, use the Candidate view to inspect the isolated file tree and the activity panel to monitor phase, elapsed time, model step, observations, execution epochs, recovery attempts, and last signal.

Model configuration

Argument	Purpose
--model	Default local model for ordinary requests and general reasoning.
--engineering-model	Preferred model for iterative workspace engineering and Goal Mode. When omitted, FAM_OS selects the strongest recognized installed coding model and falls back to --model.
--engineering-provider codex-subscription	Use the owner's authenticated Codex CLI as the native candidate engineering agent.

qwen3.8:27b is the currently exercised engineering configuration in this checkout. Smaller quantized models remain useful for focused reading, classification, and small edits, but reliable autonomous engineering depends heavily on tool-calling quality, context capacity, and available RAM/VRAM.

FAM_OS does not reload model weights for every prompt when Ollama keeps the model resident. A cold or evicted model can still make the first response slow. Residency, model size, concurrent workloads, and Ollama keep-alive settings determine that latency.

Candidate workspaces and trust

During engineering work, file mutations and commands shown in the Tool Terminal may target an isolated candidate under the FAM_OS state directory rather than the selected owner folder. This is intentional:

• Build: changes appear in Candidate view but not yet in the owner's file manager.
• Verify: tests and completion checks run against that same candidate.
• Apply: only a verified candidate is reconciled into the owner workspace.
• Failure or cancellation: candidate evidence is preserved for inspection; the owner workspace remains unchanged.

Commands execute with the selected agent-access profile. Approval and isolation are product boundaries, but they should not prevent ordinary, authorized filesystem work or force non-repository folders into Git workflows.

Architecture

Linux
  -> FAM Supervisor             resource and execution boundary
  -> FAM Core                   request, permission, and outcome lifecycle
  -> Adaptive Agent Harness     context, tools, recovery, and iteration
  -> Application Fabric         filesystem, commands, Git, apps, MCP
  -> Expert Fabric              local model selection and residency
  -> Verification Fabric        semantic and command postconditions
  -> Memory / Goal Store        conversation and durable checkpoints
  -> Authenticated Console      control, evidence, and candidate visibility

Useful implementation guides:

• Adaptive agent harness
• Workspace tool loop
• Application test harness
• Shell and Console
• Installed operation
• Application weaving
• Safe service recovery
• Native Codex engineering
• Omarchy installation and lifecycle
• Omarchy integration architecture
• Omarchy application testing
• Omarchy plugin and agent security boundary

Architecture decisions and implementation handoffs are retained under docs/decisions/ and handoffs/. They are engineering history, not a substitute for this current operator guide.

Development and verification

Run the complete test suite:

PYTHONPATH=src:. .verification-venv/bin/python -m unittest discover -s tests

For faster navigation, this repository maintains a Larry code map:

larry search "where is durable Goal Mode implemented?"
larry find GoalModeService

The active implementation lives entirely under FAM_OS/. The sibling RNF prototype and its historical artifacts are read-only evidence and are not runtime dependencies.

Project status

FAM_OS is an active Linux agent runtime with a real Arch/Omarchy packaging and release path. Version tags build and sign the official x86_64 package; an experimental aarch64 build remains non-gating and is not an Omarchy release. Official omarchy pkg add fam-os availability still depends on the focused package contribution being accepted into omacom/omarchy-pkgs. Autonomous quality depends on the selected model, hardware, project toolchain, and completion checks. A successful UI step is not proof by itself: trustworthy completion requires file, command, application or semantic evidence from the requested workspace.

License

MIT — see LICENSE.