Forcefield (ff)

Forcefield is a local-first command line tool for running AI agents.

It provides the runtime around a model: tools, skills, sessions, memory, permissions, shell execution, and provider communication. Forcefield runs as a single binary.

Forcefield does not require a local model. It works with either local or remote model providers; running a model locally is optional.

It does not require:

• A user account
• A cloud service
• Remote data processing
• Telemetry

Forcefield is under active development. Features and interfaces can change.

Features

• Local model execution through Ollama, LM Studio, and llama.cpp (llama-server)
• Support for remote model providers
• Interactive terminal interface
• Streaming responses
• Agent skills
• Agent tools
• Session storage and recovery
• Model provider abstraction
• Tool permissions
• Context management
• Project search
• Shell execution
• Secret redaction
• Agent memory

Requirements

Forcefield requires access to a supported model provider. Ollama is only required if you choose to run a local model.

• Local models: Ollama, LM Studio, or llama.cpp (llama-server), with a model installed.
• Remote models: a supported remote provider, with its required credentials/configuration.

Optional local-model example:

ollama pull ornith:9b

Go 1.22+ is only required when building from source.

Installation

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/fabledruns/forcefield/main/scripts/install.sh | sh

The installer detects amd64 or arm64 and installs ff to ~/.local/bin.

Windows

irm https://raw.githubusercontent.com/fabledruns/forcefield/main/scripts/install.ps1 | iex

The Windows installer installs ff.exe to $HOME\.local\bin and adds that directory to the user PATH when required.

The installers require no Administrator privileges and can be run again to upgrade an existing installation.

Trust and verification

The curl | sh and irm | iex commands download the installer from the main branch over HTTPS and execute it immediately. This means you are trusting the installer contents at that point in time.

For reproducible installation, pin the installer to a release tag or download the installer first and inspect it.

Release binaries include checksums.txt. The installers verify the downloaded binary against those checksums.

Checksum verification provides integrity against the published checksum file. It does not provide independent authenticity beyond the GitHub release and HTTPS trust chain.

Manual installation

1. Download the appropriate binary from GitHub Releases.
2. Rename it to ff (ff.exe on Windows) if necessary.
3. Place it somewhere on your PATH.
4. On Linux/macOS, make it executable:

chmod +x ff

Release artifacts use these names:

ff-linux-amd64
ff-linux-arm64
ff-darwin-amd64
ff-darwin-arm64
ff-windows-amd64.exe
ff-windows-arm64.exe

Version pinning

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/fabledruns/forcefield/main/scripts/install.sh | sh -s -- --version v1.0.0

Or, from a checked-out repository:

FORCEFIELD_VERSION=v1.0.0 sh scripts/install.sh

Windows:

$env:FORCEFIELD_VERSION="v1.0.0"; irm https://raw.githubusercontent.com/fabledruns/forcefield/main/scripts/install.ps1 | iex

Or from a checked-out repository:

powershell -ExecutionPolicy Bypass -File scripts/install.ps1 -Version v1.0.0

Upgrading

Run the installation command again.

The installer replaces the existing binary in place. It does not modify ~/.forcefield or project sessions.

Uninstalling

Linux/macOS:

sh scripts/uninstall.sh

Or:

curl -fsSL https://raw.githubusercontent.com/fabledruns/forcefield/main/scripts/uninstall.sh | sh

Windows:

powershell -ExecutionPolicy Bypass -File scripts/uninstall.ps1

Or:

irm https://raw.githubusercontent.com/fabledruns/forcefield/main/scripts/uninstall.ps1 | iex

Uninstallation removes the Forcefield binary only. Configuration, sessions, memory, and other files under ~/.forcefield are left untouched.

Supported platforms

Release artifacts are statically linked with CGO_ENABLED=0 and built using go build -trimpath -ldflags "-s -w".

PATH troubleshooting

If ff is not found after installation, restart the terminal so the updated PATH is loaded.

You can also check:

export PATH="$HOME/.local/bin:$PATH"
ff --version
ff doctor

The installer does not duplicate existing PATH entries or overwrite existing shell configuration.

Build from source

Clone the repository and run:

go build -o ff .

Windows:

go build -o ff.exe .

Run the resulting binary:

./ff

Usage

Start the interactive terminal:

ff

Then enter a request:

> explain this repository

Run a task directly:

ff run "inspect this repository and explain its structure"

Run diagnostics:

ff doctor

Commands

Forcefield provides both CLI commands and interactive slash commands.

CLI commands include:

ff
ff chat
ff run
ff memory
ff doctor
ff --resume <session-id>
ff --agent <name>

Sessions are project-local (.forcefield/sessions/ under the current working directory): --resume only finds sessions created in the same directory. Use /sessions in the TUI to browse them.

Inside an interactive session:

/help
/sessions
/status
/tools
/skills
/skills list
/skills show <id>
/new
/clear

/status shows the active provider, model, session information, and available tools.

Configuration

Forcefield stores its configuration at:

~/.forcefield/config.yaml

Example:

model:
  provider: ollama
  endpoint: http://localhost:11434
  name: ornith:9b

agent:
  name: default
  system_prompt: |
    You are Forcefield, a local-first coding agent.
    Complete software tasks in real repositories:
    inspect, change, run, debug, and verify.

Configuration controls the model provider, endpoint, model, and agent instructions.

Additional runtime settings are available for context management, permissions, workspace boundaries, and shell execution.

How it works

Forcefield owns the agent loop:

User
 │
 ▼
Command / TUI
 │
 ▼
Agent Runtime
 ├── Context
 ├── Permissions
 ├── Sessions
 ├── Skills
 ├── Memory
 └── Tools
       │
       ▼
   Model Provider
       │
       ▼
    Response

The model proposes operations through tool calls. Forcefield applies permission rules, executes tools, records their results, and continues the conversation.

Providers handle communication with individual model APIs. The runtime remains independent of the provider being used.

Tools

Built-in tools include:

read_file
write_file
list_files
search_files
find_files
shell
secret_scan
load_skill
memory

Tools receive structured input, perform an operation, and return a result to the runtime.

Tool execution is subject to permission rules and runtime limits.

Shell execution

Shell commands use a configurable executor.

native

Runs commands directly on the host. This is the default and preserves the historical Forcefield behavior.

wsl

On Windows, runs commands inside a WSL distribution with a pinned working directory, restricted environment, and optional network isolation.

WSL mode requires an available WSL distribution. Forcefield does not silently fall back to native execution.

WSL does not provide filesystem confinement. A WSL process can access Windows drives through /mnt.

For the full shell and sandbox configuration, see docs/Sandbox.md.

Skills

Skills are Markdown files stored globally under:

~/.forcefield/skills/

Supported layouts:

~/.forcefield/skills/review.md
~/.forcefield/skills/git-review/SKILL.md

Forcefield indexes skill metadata into a small catalog. The full skill body is loaded when needed.

Supporting files are not executed automatically.

Example:

# Go Development

Use the Go language standard.

Prefer simple designs.

Use clear error handling.

Manage skills with:

/skills
/skills list
/skills show <id>

Sessions and memory

Sessions are stored project-locally under:

.forcefield/sessions/

(relative to the current working directory — resume from the same directory). Use /sessions in the TUI to browse sessions and ff --resume <session-id> to continue one. Sessions are capped at 1000 messages with an observable [compacted N older messages] marker and a persisted compaction count; provider requests additionally use a 100-message sliding window.

Persistent project memory is scoped per project under ~/.forcefield/memory/ (capped at 200 entries / 8 KiB in prompts).

Session state is written atomically (temp + fsync + rename). Interrupted tool execution is recorded so the runtime can identify incomplete work when a session is reopened; length-truncated or incomplete provider turns block instead of reporting success.

Project search

search_files and find_files provide bounded project search.

Generated and dependency directories such as these are excluded from searches:

.git
node_modules
dist
build
target
vendor
.next
__pycache__

Search operations also limit the number of files, file sizes, matches, and execution time.

Permissions and redaction

Tool permissions use three states:

allow
ask
deny

Rules are evaluated before a tool executes.

Forcefield also redacts recognized credentials from runtime output and persisted state. Redaction covers areas such as tool results, shell output, provider errors, session data, tool arguments, memory, and diagnostics.

ff doctor does not print secret values such as API keys.

Project structure

forcefield/
├── cmd/
│   └── ff/
│       └── main.go
├── internal/
│   ├── agent/
│   ├── command/
│   ├── config/
│   ├── providers/
│   ├── runtime/
│   ├── session/
│   ├── skills/
│   ├── tools/
│   └── tui/
├── examples/
│   └── skills/
└── scripts/

Package responsibilities are separated by runtime, provider, session, tool, skill, configuration, and terminal-interface concerns.

Development

Run the test suite:

go test ./...

Build:

go build ./...

Run static analysis:

go vet ./...

Format the repository:

gofmt -w .

License

Apache License 2.0.