Documentation

Forge the output of any command into what you actually want to read.

context-forge is a C++20 command wrapper for Linux. It runs a program, captures one of its file descriptors, pushes the text through a pipeline of rule plugins (declared in small .cfg files) and, optionally, through a local Ollama model — then prints the result in place of the original output.

Install & set up

Packages for Fedora/Debian, build from source, shell completion for bash and zsh, the user daemon, Ollama.

User guide →

Use it

Every sub-command and flag, environment variables, the client/server workflow and a troubleshooting checklist.

Command reference →

Write rules

The .cfg rule format: triggers, the ansi pre-rule, block, and the ln/drop/dup/replace/insert rules.

Rule files →

Build a plugin

Technical guide: the plugin ABI, the three plugin types, a complete worked example, CMake wiring and tests.

Developer guide →

Explore the architecture

Interactive 2D/3D graph of files, classes, methods, tests, build targets and their dependencies.

Open the graph →

How it works, in one picture

If the server is not running, exec falls back to running the command untouched, so a wrapped command never breaks.

Quick start

Install the binary — from the signed package repository or from source. Installation →

sudo curl -fsSL -o /etc/yum.repos.d/context-forge.repo https://tsukini22.github.io/context-forge/context-forge.repo
sudo rpm --import https://tsukini22.github.io/context-forge/RPM-GPG-KEY-tsukini
sudo dnf install context-forge

Write a rule file — say ~/forge/rules/ls.cfg:

trigger = { bin = ["ls"]; };   // only for `ls`
drop = ["^total \\d+"];         // remove the "total N" line

Register the daemon with your plugin and rule directories (plugins ship in the repo's plugins/ folder after a build):
```
context-forge setup --copy --recursive --plugins ./plugins --rules ~/forge/rules
context-forge status
```
Wrap a command:
```
context-forge exec -c ls -la
```

Two halves. The rule engine works entirely offline. The LLM pass only activates when the server was started with a --system-prompt file and can reach an Ollama instance; otherwise it is silently skipped.

Vocabulary used across these docs

Term	Meaning
client	The `context-forge exec` process: spawns your command, captures one fd, talks to the server.
server	The long-lived `context-forge server` process (installed as `context-forge.service`, a systemd user unit) that owns plugins, rules and the Ollama client.
plugin	A shared object (`*.so`) exporting `type()`, `name()` and `factory()`. One of three kinds: trigger pre-rule rule.
rule file	A libconfig `.cfg` file. Each top-level key names a plugin (or one of the two built-ins, `enable` and `block`) and carries its settings.
bin	The name of the wrapped program (`argv[0]` as given to `-c`), passed to every plugin so rules can react per program.