falsegreen-agent
falsegreen-agent is a bounded local Rust coding-agent harness. It turns a human-frozen task into
workspace-confined model/tool activity and submits candidate source to canonical FalseGreen. The
worker, its tests, and candidate_ready can never mint acceptance.
FalseGreen verification and permission to claim completion are deliberately separate:
verification Accepted + authority_ready=false + may_claim_complete=false
-> AcceptedAwaitingAuthority (not Completed)
verification Accepted + authority_ready=true + may_claim_complete=true
-> Completed
verification Failed/Incomplete/Invalid
-> bounded repair path or Failed
NeoHorse-1-9B Q8_0 is the selected V1 reference/default model. The agent remains model-neutral
behind InferenceProvider, ModelCapabilities, and its OpenAI-compatible provider.
The normal CLI provides an Ollama-free managed local stack. It detects the host, acquires the pinned
llama.cpp build and NeoHorse artifact into a verified user cache, starts an owned loopback-only
llama-server, connects configured MCP servers through rmcp, and uses the statically linked
FalseGreen Core client. Valid cached artifacts are reused on later runs.
Build and verify
Install and run
falsegreen-agent login prompts for an enrollment key and stores the resulting session in the same
protected platform credential store used by the standalone falsegreen client. The enrollment key
is not retained. Existing standalone credentials are discovered automatically. Authentication can
be inspected or revoked without installing the standalone binary:
The first managed run downloads the pinned llama.cpp runtime and the 9,527,501,632-byte NeoHorse
model, verifies their exact sizes and SHA-256 digests, then starts a private loopback server. Allow
at least 11 GB of free cache space. The cache defaults to the platform/XDG cache directory and can
be overridden with FALSEGREEN_AGENT_CACHE_DIR or --cache-dir.
Normal V1 run
Run the agent from the Git repository it may change. The run subcommand and
--workspace are optional:
The current directory becomes the confined workspace. Durable event state is placed outside it, NeoHorse is the pinned managed default, FalseGreen is the embedded completion boundary, and configured MCP servers are discovered. When no paused session or saved task exists, an interactive commandless run prompts for the coding goal and FalseGreen task ID. A later command with no goal resumes the most recent safely paused session:
Use falsegreen-agent doctor for readiness checks and --json for automation.
See the one-command UX contract.
An infrastructure-failed terminal session that already contains complete candidate provenance may be replaced explicitly without reopening it or invoking the model again:
Replacement creation is fail-closed, permits one direct replacement with no chains, and atomically records both a first-class relation and durable event. Resume requires the exact inherited Task, candidate, and full Git/workspace identity. Replacement sessions are verification-only: canonical rejection cannot reopen model repair. See the replacement-session contract.
Advanced external-provider run
An explicit endpoint bypasses managed acquisition. Pinned NeoHorse still requires the exact named artifact and digest, but an arbitrary external runtime never inherits a full-stack qualification:
The verifier is the statically linked FalseGreen Rust client and uses the protected session created
by either falsegreen-agent login or falsegreen login. Normal agent operation and authentication
do not launch or require a separately installed falsegreen executable. FALSEGREEN_API_URL
remains the compatible endpoint override.
Pinned Core dependency
Cargo.toml pins truemagic-coder/falsegreen by exact Git revision and
Cargo.lock records the same source. To update Core, review a specific Core
commit, replace only the dependency rev, update the lockfile, then run the
full format, lint, authority-boundary test, and release-build commands above.
Never replace the immutable revision with a branch or tag, and never carry a
lockfile that resolves a different Core commit.
The selected profile fixes repository, revision, artifact digest, Q8_0 quantization, 8,192-token context, runtime family, and MTP-disabled setting. The normal path obtains the model and runtime automatically and uses the embedded FalseGreen client. The official managed llama.cpp packages are a different distribution/backend from the prior frozen qualification and therefore remain unqualified until their own full-stack qualification succeeds. See the exact profile and managed runtime contract.
An experimental provider/model must be explicitly marked unqualified:
Qualified-profile metadata cannot be overridden piecemeal. An unqualified configuration never inherits the V1 qualification claim.
Durable operation
The event database must be outside the implementation workspace. Every model request, response,
tool request/result, candidate, verification, repair, state transition, and source fingerprint is
append-only. Use --pause-after-model-turns N to end a process at a persisted turn boundary; resume
with --session session_.... Resume verifies the exact checkpoint candidate fingerprint before
another model request or tool call.
Terminal history is immutable. A supported replacement creates a distinct CandidateReady
session linked to one infrastructure-failed predecessor, verifies the current workspace against
the carried candidate and complete Git provenance before runtime setup, and goes directly to
canonical verification on explicit resume. It never treats the predecessor as active, never
invokes inference to adopt the candidate, and cannot enter model repair after a non-accepted
verification result.
Exit codes distinguish the authority states: 0 means authoritative Completed, 3 means
canonical Accepted awaiting completion authority, 75 means an intentional resumable pause,
and other nonzero results are non-complete.
Native tools are read_file, search, apply_patch, bounded argv-based shell, and read-only
git. Paths are workspace-confined; patch paths are checked; command time/output and file reads are
bounded; unknown or malformed calls fail safely. This is a local development boundary, not a
production security sandbox.
Track 5 adds an optional trusted GenUI/GenTUI presentation seam. --genui
augments human run output with a deterministic terminal surface; it does not
replace chat, generate UI code, emit ANSI, or become an authority surface.
The versioned component/action contract, MCP schema adapter, bounds, stale
action checks, and security rules are documented in
docs/GENUI_TRACK5.md. FalseGreen Core remains the
only acceptance authority.
This release ships the accepted Agent foundation, FalseGreen-native state surfaces through G4, and the independently accepted G5 V10 generative composition path. G5 remains a constrained, read-only presentation composition layer: trusted handles and host-owned authority are required, model proposals cannot grant execution authority, and live fences preserve the existing workspace, durable-state, MCP, policy, confirmation, and renderer boundaries. See the G5 composition contract.
Optional MCP tools can be discovered from strict versioned JSON with --mcp-config PATH. The
official Rust rmcp SDK supplies stdio and Streamable HTTP transport, initialization/capability
negotiation, tools/list, tools/call, cancellation, and cleanup. Remote tools are exposed through
stable collision-resistant mcp__... names and retain bounded durable call provenance. See the
MCP client configuration.
See architecture, V1 qualification, model decision, and dogfood history.