CG Agent Harness

CG Agent Harness combines chat, files, memory and selected tools locally.

Watch the silent 60-second demo · Voiceover cues and recording notes. A synthetic release review in separate native and web sessions; edited for pacing.

Quick start · Engineering choices · Security and defaults · Documentation

What you can do

Capability	What it provides	Starting state
Local chat	Streaming sessions, attachments, skills, prompt inspection, and bounded goal continuation with owned attachments and permitted web tools through /loop.	Loopback model service; Ollama by default.
Memory	Shared pinned notes plus account-private structured facts, recall, and proposed summaries or insights.	Capture, retrieval, and suggestions on; applying proposed facts requires review.
Web research	Google listings, permitted page fetches, and research with request, time, byte, and token budgets.	Web tools on in allowlist mode with an empty content allowlist; search results never authorize page reads.
Reviewed coding	A planner/executor loop, isolated repository clones, checks, complete diff review, and separate Git decisions.	Disabled until configured for a selected repository.
Jobs and schedules	Detached coding jobs and reviewed interval or cron schedules.	Same coding permissions and owner-bound review.
Cloud chat	Optional Grok or Claude. Sends only the new message, never local history, memory, skills, attachments, or web context.	Requires provider setup; unavailable for /loop.
MCP integrations	Declared external tools and a separate read-only memory gateway with dedicated machine credentials.	Both disabled.
LAN observation	Netconnect reads in-scope interfaces, routes, and neighbors from local tables.	Disabled with empty scope; the only active tier is the budgeted diag TCP probe; no scans or device control.
Self-knowledge	A bundled harness manual and a live status block as untrusted local-chat context.	On; never sent to cloud chat, /loop or /agent.
Log diagnostics	/diag shows bounded, redacted tails of allowlisted home logs.	Disabled; admin or portal_auditor only.

Open Memory to review your pending proposals after completed work; enter a reason to apply or dismiss. Suggestion activity explains missing proposals. Setup.

Starting states describe fresh homes; upgrades keep existing choices. Only /web research produces checked quote references. See the console guide.

How reviewed coding works

1. Scope. Select a repository, configure the coding gates, and prepare its toolchain.
2. Stage and confirm. Specify the instruction, branch, allowed reads, and check profile.
3. Generate and verify. The pipeline applies bounded edits in its own clone and runs checks in a sandbox.
4. Review. Inspect the full diff and check results; explicit approval commits.
5. Publish deliberately. Push and draft pull-request creation each require a separate reason and confirmation.

Passing checks never authorize publication; scheduled jobs use the same controls. Start with Coding pipeline and its Git approval contract.

Engineering choices

Decision	Purpose	Explore
Separate console and coding processes	Agentic execution sits behind an allowlisted subprocess interface.	Shim, invariant tests
Bind approval to reviewed changes	Accepted content, file modes, destination, and commit are rechecked at every Git step.	Git approval, tests
Separate memory proposals from facts	Models suggest; changing canonical facts requires approval.	Memory guide, tests
Bound external work	Limit research, model calls, subprocess execution, and tool results.	Configuration, process lifecycle
Treat installation as part of the system	The app owns its backend, keeps state outside the bundle, and is identified by commit.	Desktop, releases

Stack: Rust, Tokio, Axum, SQLite, Tantivy, and Tauri for the macOS desktop shell.

Quick start

A home is the application's state directory: ~/.CGagentHarness, overridden with CGAGENTHARNESS_HOME. Run one app or standalone server per home.

macOS, from scratch: after xcode-select --install and a clone, scripts/install-macos.sh installs what is missing (Rust, Ollama, the release app) and builds the backend; scripts/start-macos.sh opens the app and its console in your browser. See automated install and browser access. The steps below are the manual path.

1. Prepare a local model

Pick an installed model that fits your hardware (ollama list); the default qwen3.8:27b-mlx-cg is a locally derived tag, not bundled or required.

The default endpoint is http://127.0.0.1:11434/v1. Seeded research budgets assume a 32,768-token context window; for a terminal-managed Ollama service, set it at startup:

OLLAMA_CONTEXT_LENGTH=32768 ollama serve

Restart an existing service rather than starting a second daemon. The harness sends no num_ctx; see Models for Ollama.app, smaller windows, and a local derived tag that pins 32768.

Other OpenAI-compatible services work on any loopback address (127.0.0.1, localhost, or [::1]); chat and the coding planner have separate settings.

2. Choose how to run the harness

macOS app

Download CG-Agent-Harness-macos-universal.zip and SHA256SUMS from Releases, then run from the download directory:

shasum -a 256 -c SHA256SUMS
unzip CG-Agent-Harness-macos-universal.zip
open "CG Agent Harness.app"

The universal app (Apple Silicon and Intel) runs its backend on an ephemeral loopback port and needs no Rust, Python, or browser; coding checks need their own tools. Bundles are ad-hoc signed; see Desktop for Gatekeeper and tested platforms.

Standalone server: macOS or Linux

Source builds use Rust 1.88. macOS requires Xcode Command Line Tools; Linux requires a C toolchain (Install).

git clone https://github.com/cgfixit/CG-agent-harness.git
cd CG-agent-harness
cargo build --release --locked
./target/release/cgagentharness serve

Open https://127.0.0.1:8790/ and trust the local certificate (certificate guide). Non-loopback binds are refused.

To build the macOS app from source (Apple Silicon host, Rust 1.88 and 1.90), see macOS app installation.

3. Sign in and try a conversation

1. Fresh homes open Set your password. Enter the private setup code and a new password. In the app, Cmd and + (Cmd, Shift, =) opens Setup and recovery, which shows the code; terminal users read <home>/setup-code.
2. List installed local tags with /model list, then select one with /model use <exact-installed-tag>. With models.local_llm.auto_tune (on by default) this also measures the model and sets per-model limits; /model profile shows them.
3. Read the header chips: Console (API reachable), Model (selected tag installed at the loopback Ollama endpoint; other providers read not checked), and Web (off, not configured, search only, or URL rules; administrators also see a globe beside it that shows and switches the policy mode). Then run /status, send a message, and inspect the assembled context with /prompt.
4. Run /help for topics, /help web for research, or /help all for the command catalog.

Start coding only after the separate coding setup.

Security and defaults

• Local access: fresh homes require HTTPS and account login. The optional harness API key does not replace account authentication.
• Repository changes: agentic.enabled, agentic.deepagent_github.enabled, and allow_git_write_tools ship false; some write-mode and provider settings do not, so review the combined policy before enabling execution.
• Web policy mode: homes ship in allowlist mode. An administrator can switch the whole home to block-list mode after a confirmation dialog; chat, /loop, fetch, and research then read any public URL no block rule covers. Private and local addresses stay refused in both modes.
• Network boundaries: loopback binding limits incoming access only; research, cloud providers, subprocesses, and external model runtimes still reach the network.
• Cloud coding: six gates end in per-run --confirm-online. Requests can send repository excerpts and task context before diff review; redaction does not remove proprietary code.
• Sandbox differences: macOS uses Seatbelt. Linux prefers bubblewrap; its unshare --net fallback isolates networking without equivalent filesystem confinement.
• Data scope: structured memory and sessions are account-owned; other home state is shared. This is not tenant isolation.
• Credentials and records: provider keys default to the OS credential store; audit records use secret-pattern and startup-key redaction and stay under the home.

The deployment model is a local operator workstation; Windows builds and releases remain parked. Read Security, Invariants, and Secure research for boundaries and limitations.

Command line

Each command supports --help.

Command	Purpose
cgagentharness serve	Start the console.
cgagentharness account	Login, password, identity, logout.
cgagentharness web	URL permissions, search, fetch, research.
cgagentharness tls	Certificate inspection and renewal.
cgagentharness mcp-key	Memory-gateway machine keys.
cgagentharness netconnect	Gate status, passive devices, and the budgeted diag TCP probe.

Configuration and verification

First launch seeds the home's config.yaml from the defaults; edit that copy. Permission gates require literal YAML true; quoted "true" or a missing key does not enable them. Startup logs any setting that ships true but is absent from your config.yaml, and /memory lists the structured-memory ones. Most settings require restart; selected web/API limits support live reload.

Before contributing, run bash scripts/ensure-githooks.sh and inspect its output (hook guide). Follow AGENTS.md for focused local verification. For comprehensive checks:

SKIP_LIVE=1 scripts/verify-local.sh

CI adds invariant guards, browser acceptance, sandbox and MCP lifecycle, and security scanning; see Tests and CI/CD and Actions.

Identify builds by commit, not the Cargo version 0.1.0: check the app's Contents/Resources/COMMIT, workflow SHA, and release notes; main can be newer than published binaries.

Documentation

Topic	Guide
Setup, upgrades, backups, recovery	Install, Troubleshooting
Models	Models
Chat, attachments, skills, connectors, commands	Console
Memory behavior and ownership	Memory, Structured memory
Coding, jobs, schedules	Coding pipeline
External tools and private memory access	MCP client, MCP server
Passive LAN observation	Netconnect
Usage, costs, completion webhooks	Analytics, spend and notifications
API, dependencies, releases	Routes, ,

License

MIT.