Sean McDonnell 的 Rust 个人工作助手 Harness 1.3.0

Harness is Sean McDonnell's personal work assistant, written in Rust. It reads and edits repositories, runs tools, keeps resumable sessions, and offers a terminal interface and a local web interface. Persistent workflows cover software, research, documents, websites, automation, and Apple projects. The repository is public and MIT licensed. Development is focused on dependable personal use.

You choose the exact provider:model route. The first entry is primary; optional fallbacks run in your chosen order. Credentials never rank providers or insert a fallback. Built-in provider names are presets, and custom OpenAI-compatible endpoints can be configured without adding Rust code.

Current status: version 1.3.0, under active maintenance. Build and verify the current source before use; a successful build does not establish every optional integration or operating system. The assessment and acceptance record distinguishes verified workflows from remaining checks. Earlier competition, promotion, and release notes are historical.

Build and verify

Install Git and Rust through rustup. The repository pins Rust 1.95.0.

git clone https://github.com/seanebones-lang/harness.git
cd harness
cargo build --locked
./target/debug/harness --version
./target/debug/harness --help
make verify

make verify runs workspace formatting, strict linting, tests, and synthetic agent/HTTP acceptance. Its tests do not require API keys. For an optimized binary:

cargo build --locked --profile release-lto
mkdir -p ~/.local/bin
install -m 755 target/release-lto/harness ~/.local/bin/harness

On Windows, copy target\release-lto\harness.exe into a directory on your user PATH. The installation guide covers platform tooling and installer scripts. Prebuilt releases may lag source; use the freshly built executable when checking new behavior.

First use

Make the chosen provider's credential available through its documented environment variable, or run a local backend such as Ollama. Harness setup stores environment-variable names rather than new secret values.

cd /path/to/your/project
harness setup
harness route show
harness doctor
harness

Select your own provider and model in setup. An explicit ordered route can also be saved with harness route set <provider>:<model> [...]. Run harness route --help for scope and custom-endpoint options. Provider configuration explains compatible endpoints; the user manual covers first use.

harness "explain this repository"
harness --plan "refactor this function and show the proposed changes"
harness --resume <session-id> "continue"
harness sessions
harness export <session-id>
harness cost today

A failed or token-limited one-shot run exits with an error and saves its session for inspection or resume. Session exports retain full tool results. Tool execution limits stop an incomplete run rather than claiming completion.

Build a backend, RAG service, or automation

Start with an outcome and observable acceptance criteria:

cd /path/to/your/project
harness build "Build a local document retrieval API in Python" \
  --accept "Ingested documents retain source identifiers" \
  --accept "Answers cite retrieved sources; empty retrieval is explicit" \
  --accept "The API starts locally and handles malformed requests" \
  --check "python3 -m pytest"

This saves an editable .harness/build.toml and runs the existing agent. It discovers verification commands from existing root manifests when none are supplied. Use --prepare-only to review the brief without API calls. Repeating --accept or --check supplies the respective list; omitted lists keep existing values when continuing the same outcome. A different outcome archives the prior brief and progress notes.

Run harness build to continue the saved outcome, or harness --resume <session-id> build to also reuse a conversation. Build runs save their session ID, turn status, and recent shell/test output in .harness/BUILD_PROGRESS.md, even when the model omits notes or the run fails. The terminal and HTTP agent load the same brief and progress alongside project instructions. Recheck those observations against the workspace; a finished turn does not certify acceptance. The brief itself does not prove completion or execute checks; the agent must run them and report their evidence. Supply checks appropriate to your repository and review any detected commands.

Use it across your work

Choose an existing project or work folder with -C, then describe the outcome:

harness -C "/path/to/work" work --kind research "Compare these sources and save a cited report"
harness -C "/path/to/work" work --kind documents "Revise this proposal and verify its figures"
harness -C "/path/to/site" work --kind website "Fix booking validation and verify the phone layout"
harness -C "/path/to/job" work --kind automation "Add a dry run and prevent duplicate processing"
harness -C "/path/to/app" work --kind apple "Fix the failing simulator build"
harness -C "/path/to/backend" work --kind software "Add a sourced retrieval endpoint"

work uses the same runner, editable brief, observed receipts, and session recovery as build. Use harness -C "/path/to/work" work to continue its saved kind and outcome. Add --prepare-only for a local brief with no provider calls; --accept and --check customize its criteria and commands. Old build briefs still load as software. Changing the kind requires an explicit outcome and archives earlier progress. Research and document briefs do not automatically detect repository test commands.

Preparation installs the matching bundled SKILL.md and any helper into .agents/skills/. CLI, terminal, and HTTP context include skill names, descriptions, and paths; the agent reads matching instructions and supporting files only as needed. Existing skills are preserved. harness skills list reports bundled workflows, project skills, and invalid or duplicate metadata; harness skills install documents installs a workflow independently of a brief.

You can place a reviewed skill folder from OpenAI's skills repository or your own workflow in .agents/skills/<name>/SKILL.md (or .harness/skills/). Harness reads YAML name and description; it does not implement upstream plugin metadata, connectors, tool grants, or installer behavior. Supporting paths resolve relative to the skill folder. Keep the source skill's license with imported files and verify its tools and dependencies before using it. Project skills follow the existing file/shell approval boundaries and are limited to the workspace; external symlinks are rejected during discovery and installation.

The document helper can extract bounded, source-labeled text from DOCX, XLSX, PPTX, CSV/TSV, Markdown, and text with Python 3. PDF extraction needs Poppler's pdftotext. It labels spreadsheet formula results as cached, reports truncation, and never implies layout review or recalculation:

python3 .agents/skills/documents/scripts/extract.py --probe
python3 .agents/skills/documents/scripts/extract.py "input.xlsx"

Formatted document creation uses appropriate optional libraries; the dependency probe reports common packages without installing them. Browser review needs configured browser tooling and a model capable of inspecting images. Research uses the search tools actually loaded for the selected provider or MCP connection; otherwise it works from supplied sources or known URLs and reports that boundary. A workflow supplies guidance and tested local mechanics; completion remains dependent on the model and configured integrations.

Attach a screenshot or rendered page to a one-shot request, run, build, or work with --image:

harness -C "/path/to/site" work --kind website "Review this phone layout" --image "preview.png"

The OpenAI-compatible transport sends image bytes as multipart user content and retains them in the saved session. Native Anthropic, xAI, Ollama, and Bedrock adapters currently reject image attachments explicitly rather than dropping them. PNG, JPEG, GIF, and WebP attachments must be nonempty and at most 10 MiB. Choose a route that supports image input; transport acceptance does not prove a model interpreted or visually validated the image.

Useful capabilities

• Repository tools: reading, writing, patches, search, shell commands, Git, GitHub CLI, and test execution.
• Sessions and memory: SQLite conversation storage, session export, project instructions, optional semantic recall and ambient consolidation.
• Workers: tracked swarm tasks, cancellation, cleanup, wall-time limits, tool allowlists, and explicit worker model routes.
• Interfaces: terminal UI, one-shot commands, local HTTP/SSE server, and a daemon. VS Code and Tauri clients are optional.
• Interop: MCP tools/resources/sampling and LSP lookups. Browser, computer use, database, notebook, Docker, voice, and platform bridges are optional integrations with their own setup.
• Deadbolt: an out-of-band control for agent tool/MCP/spawn authority. See its scope and commands.

Use optional integrations when they solve a real task. They are not requirements for the core coding workflow.

Local web interface

harness serve --addr 127.0.0.1:8787

Open the address printed by the server. API requests require its bearer token; keep the service on loopback for personal use. Container instructions cover a separate runtime environment.

Trust and recovery

Tools act with the authority of your account. Filesystem restrictions, plan approvals, and Deadbolt controls do not establish arbitrary-code isolation for a shell command. Review the trust boundaries, use plan mode for changes you want to inspect, and keep work in version control. Cancellation and timeouts are part of the agent's runtime contract.

Credentials and personal state belong outside the public repository. Local .env files are ignored. The automated acceptance scripts use isolated temporary homes and synthetic providers.

Development

The current backlog orders the remaining work. The developer map explains the modules, and the architecture describes the existing design. The cookbook and keyboard reference cover detailed workflows. Coverage measurements in COVERAGE.md are dated evidence; the workflow badge reflects CI status.

make verify
make web-test
make supply-chain

Provider changes should include mock transport tests for split network chunks, terminal conditions, and tool-result continuation. Preserve exact user-selected routes. OpenAI's Codex repository, Agents SDK, and Python SDK are implementation references; their licenses remain separate, and Harness does not imply complete API or feature parity.

Contributions follow the MIT license and contribution guide.