Command reference

One binary, eleven sub-commands. The first positional word selects the mode; flags accept a short form (-c), a one-dash long form (-cmd) and a GNU form (--command).

Synopsis

context-forge -h | --help
context-forge exec    [-v LEVEL] [-d FD] [-n] -c BIN [ARG...]
context-forge server  [-P DIR] [-r DIR] [-R] [-s FILE] [-a IP] [-p PORT] [-m MODEL] [-v LEVEL]
context-forge check   local [same flags as server]
context-forge check   dist  [-a IP] [-p PORT] [-m MODEL] [-v LEVEL]
context-forge setup   [-C] [same flags as server]
context-forge start | stop | restart | remove | install-ollama   [-v LEVEL]
context-forge status  [-a IP] [-p PORT]
context-forge pull    MODEL

Every mode accepts -h/--help, which prints the usages the argument parser knows for that mode.

exec — wrap a command

context-forge exec [-v LEVEL] [-d FD] [-n] -c BIN [ARG...]

Spawns BIN ARG..., captures the file descriptor selected by -d (default 1, stdout) through a pipe, hands the captured text to the server, and writes the server's answer to that same descriptor once the child has exited. Everything after -c BIN belongs to the wrapped program, so put context-forge's own flags before -c.

Exit status is the wrapped program's: its exit code, or its signal number if it was killed. Descriptors that are not captured are inherited as-is, so exec -c make still streams stderr live while stdout is buffered for formatting.

Failsafe: if the systemd unit is missing, stopped or crashed, exec prints [FALLBACK] on stderr (unless -v none) and replaces itself with the plain command. A wrapped command therefore always runs.

server / check — run or validate the daemon

context-forge server [-P DIR] [-r DIR] [-R] [-s FILE] [-a IP] [-p PORT] [-m MODEL] [-v LEVEL]

Loads plugins, then rule files, then the Ollama client, creates the shared-memory channel and loops forever answering clients. You rarely run it by hand — setup generates a unit that does — but it is handy in a terminal with -v debug while writing rules:

context-forge stop      # free the unit first: the client always talks to the systemd unit's PID
context-forge server -R -P ./plugins -r ./rules -v debug

check performs the load phase and exits, reporting each plugin/rule/LLM problem instead of ignoring it:

context-forge check local -R -P ./plugins -r ./rules -s ./system-prompt -v debug   # validate given paths
context-forge check dist -v debug                                                   # validate ~/.config/context-forge/* (after setup --copy)

setup · start · stop · restart · status · remove

install-ollama · pull

Flags shared by server, check and setup

Environment variables

The argument parser declares an environment fallback for some flags. They are useful in the generated unit (add Environment= lines) or in CI:

An explicit flag always wins over the variable.

What happens on exec

1. The client asks systemd for the unit's main PID and opens the POSIX shared-memory segment named context-forge:<pid> (created by the server: 10 channels of 4 KiB; larger payloads are chunked and reassembled).
2. The payload is bin + a DLE byte (0x10) + the captured text. bin is exactly the BIN word you passed — ls, not /usr/bin/ls — and is what triggers compare against.
3. For each loaded rule file, in load order: if its triggers accept (bin, content), the file's block/pre-rules/rules are applied to the content, and the result feeds the next file.
4. If the LLM pass is active, the text is sent to Ollama and replaced by the model's response.
5. The client writes the answer to the captured descriptor (adding a final newline unless -n) and exits with the child's status.

Recipes

Alias a command for good

alias ls='context-forge exec -c ls'
alias grep='context-forge exec -c grep'

Because of the fallback, the aliases keep working when the daemon is down. Note that with an alias, bin seen by triggers is still ls.

Reformat only stderr

context-forge exec -d 2 -c clang++ -Wall main.cpp

Wrap a build tool's summary

trigger = { bin = ["make", "ninja"]; };
ansi = false;
drop = ["^\\s*$", "^make\\[\\d+\\]: (Entering|Leaving) directory"];
ln = { tail = 40; };

Ask the model for a summary of the whole output only

Give the server a system prompt and no rules directory. Everything you wrap goes straight to the model.

Troubleshooting