harness-integration-guide
Skill1 starsChanged 4 months agoApache-2.0View on GitHub
Reference guide for building new OmniCraft harness integrations — covers SDK/subprocess harnesses and native harnesses as separate tracks, each with their own feature matrix, implementation patterns, and prioritized checklist.
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- omnigent-ai/omnigentedited, first seen Oct 21, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- omnigent-ai/omnigent★ 11k78% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- antigravity-native-e2e-devSkill
- antigravity-sdk-e2e-devSkill
- cli-setup-verifySkill
- copilot-sdk-e2e-devSkill
- cursor-sdk-e2e-devSkill
- fucho-e2e-devSkill
- pi-native-e2e-devSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 72
When a policy verdict is ASK, the harness must surface the pending tool call or tool result in the OmniCraft web UI as an approval card, …
- Distinctive: line 99
All capabilities are required for a complete harness integration:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Harness integration guide
This skill describes the feature matrix every OmniCraft harness must consider. Use it when planning, reviewing, or implementing a new harness.
OmniCraft has two distinct harness tracks with different architectures and feature sets:
- SDK/subprocess harnesses — run the vendor model directly (in-process SDK, CLI subprocess, or ACP subprocess). They own the model lifecycle.
- Native harnesses — wrap a vendor's own TUI or server and mirror its output into OmniCraft. They observe and relay, rather than drive.
Part 1 — SDK / subprocess harnesses
These harnesses run the vendor model directly and bridge OmniCraft tools into the vendor's tool-calling interface.
Capability matrix
| Capability | What it means |
| Connects to OmniCraft MCP | Harness exposes/consumes tools via the MCP protocol (in-proc SDK MCP server) |
| Model override | User can select a model via --model / config; some harnesses are vendor-locked (e.g. Claude-only, GPT-only, Gemini-only) |
| Auth | How credentials are obtained — API key, gateway token, vendor CLI login, OAuth, etc. |
| Streaming | Harness forwards token-level or delta-level streaming to the OmniCraft forwarder |
| OmniCraft policies | Harness enforces OmniCraft-side tool policies — must support ALLOW, ASK, and DENY verdicts for both tool calls and tool results |
| Native elicitation | When a policy verdict is ASK, the harness surfaces the approval request in the OmniCraft web UI so the user can approve or deny |
| Interrupt | User can cancel a running turn mid-stream |
| Live queue (concurrent) | Multiple turns can be queued and processed concurrently |
| Tool-boundary steer | OmniCraft can inject steering text at tool-call boundaries |
| Resume/fork from OmniCraft transcript | Rebuild a conversation from a stored OmniCraft transcript (replay history, seed prompt, or vendor session ID) |
| Compaction | Long conversations are compacted; harness surfaces CompactionComplete events |
| Reasoning | Model reasoning/thinking tokens are forwarded |
| Images | Image content (screenshots, diagrams) is forwarded — full binary, path reference, or text-flattened |
| Cost tracking | Harness reports token usage and cost data back to OmniCraft for each turn |
MCP connectivity
The harness must bridge OmniCraft's builtin MCP tools so the model can call them. These tools provide session management, agent orchestration, policy control, and web access:
sys_session_get_info,sys_session_list,sys_session_get_historysys_agent_get,sys_agent_list,sys_agent_downloadsys_call_async,sys_cancel_async,sys_cancel_tasksys_read_inboxsys_add_policy,sys_policy_registryload_skilllist_comments,update_commentweb_fetch,web_search
OmniCraft policies
The harness must support the OmniCraft policy engine's three verdicts at two checkpoints:
| Checkpoint | ALLOW | ASK | DENY |
| Tool call (before execution) | Proceed silently | Surface approval request to user (via elicitation) | Block the call and return a policy-denied error to the model |
| Tool result (after execution) | Return result to model | Surface result for user review before returning | Suppress the result and return a policy-denied error to the model |
Native elicitation
When a policy verdict is ASK, the harness must surface the pending tool call or tool result in the OmniCraft web UI as an approval card, then relay the user's approve/deny decision back to the harness to continue or block execution.
Resume / fork strategies
| Strategy | How it works |
| Full history replay | Replays the entire message history into a fresh thread/session |
| History prefix replay | Replays a prefix of the history into a fresh session |
| Text-prefix replay | Injects a text summary/prefix of prior history |
| Prompt seeding | Seeds prior history into the system prompt on rebuild |
| Vendor session ID | Relies on the vendor's own session persistence (no OmniCraft-side rebuild) |
Auth patterns
| Pattern | Description |
| API key / Databricks gateway | Direct API key or routed through a Databricks gateway |
| Vendor API key (direct) | Vendor-specific API key (e.g. Cursor, Gemini) |
| Vendor CLI login / config file | Credentials stored in a vendor config file or managed via vendor CLI login |
| OAuth / GitHub token | OAuth flow or platform token (e.g. GitHub PAT) |
| Gateway + fallback | Primary gateway with fallback to vendor-native auth |
Checklist for a new SDK/subprocess harness
All capabilities are required for a complete harness integration:
- Connects to OmniCraft MCP (in-proc SDK MCP server or vendor-specific bridge)
- Model override works (or document vendor lock-in)
- Auth is configured and documented (setup flow in
omni setup) - Streaming forwards to the OmniCraft forwarder
- OmniCraft policies enforce tool-use rules
- Native elicitation surfaces tool-approval requests to web UI
- Interrupt cancels the running turn
- Live queue supports concurrent turns
- Tool-boundary steering injects correctly
- Resume/fork rebuilds conversation from OmniCraft transcript
- Compaction is surfaced (
CompactionCompleteevents) - Reasoning tokens are forwarded
- Images are forwarded (full binary preferred; path or text-flattened acceptable)
- Cost tracking reports token usage and cost per turn
- Unit tests cover tool bridging, auth, model routing
- Mock LLM tests cover the happy path without real API calls
Part 2 — Native harnesses
Native harnesses wrap a vendor's own TUI or server and mirror output into OmniCraft. They relay the vendor's conversation into the OmniCraft session.
Capability matrix
| Capability | What it means |
| Transport | How the native harness communicates — tmux TUI, app server, HTTP/SSE, file-inject TUI |
| Connects to OmniCraft MCP | Whether the native harness connects to the OmniCraft MCP server |
| Model override | User can select a model at launch or per-prompt |
| Auth | Vendor login / config / token |
| Streaming (forwarder) | deltas (token-level) vs complete-only (full response after completion) |
| OmniCraft policies | Whether the native harness enforces OmniCraft-side tool policies — must support ALLOW, ASK, and DENY verdicts for both tool calls and tool results |
| Native elicitation | When a policy verdict is ASK, the native harness surfaces the approval request in the OmniCraft web UI so the user can approve or deny |
| Interrupt | User can abort a running turn |
| Bidirectional sync (TUI->Omni) | TUI output mirrors into the OmniCraft conversation |
| In-harness session-cmd sync | Supports clear, fork, resume, switch commands from OmniCraft |
| Resume/fork from OmniCraft transcript | Can rebuild conversation from OmniCraft transcript (native rebuild, or fresh launch) |
| Compaction | Vendor-internal compaction status |
| Reasoning | Model reasoning/thinking tokens are forwarded |
| Images | Image content is forwarded — path reference, full binary, or text-flattened |
| Cost tracking | Native harness reports token usage and cost data back to OmniCraft for each turn |
| Tool-output streaming | Live incremental command/tool output (outputDelta) vs final aggregated output only |
| Working-tree diff | The vendor's aggregated per-turn diff is surfaced (vs reconstructed from per-file edits) |
| Generated/viewed media | Model-produced or model-viewed images are mirrored (distinct from user-supplied image input) |
| Vendor modes | Vendor-specific modes (review mode, plan mode, etc.) are mirrored as status |
Checklist for a new native harness
Capabilities are tiered by how essential they are. P0 must work or the harness is non-functional. P1 is required for a complete, parity-level integration — the web surface should match what the vendor TUI shows. Stretch items depend on vendor-specific signals and improve fidelity; they are optional and may legitimately be closed as wontfix when the vendor provides no signal or the data is redundant.
P0 — core (non-functional without these)
- Transport chosen and implemented (tmux TUI, app server, HTTP/SSE)
- Connects to OmniCraft MCP
- Auth configured (vendor login / config)
- Streaming forwarder works (deltas preferred; complete-only acceptable)
- OmniCraft policies enforce tool-use rules (ALLOW / ASK / DENY at both tool call and tool result)
- Native elicitation surfaces tool-approval requests to web UI
- Interrupt aborts the running turn
- Bidirectional sync mirrors TUI output into OmniCraft conversation
- Cost tracking reports token usage and cost per turn
- Unit tests cover forwarder, auth, transport
- Mock LLM tests cover the happy path without real API calls
P1 — parity (required for a complete integration)
- Model override works at launch and per-prompt (or document vendor lock-in)
- Session commands (clear, fork, resume) work from OmniCraft
- Resume/fork rebuilds from OmniCraft transcript
- Reasoning tokens are forwarded
- Compaction status is surfaced
- User-supplied images are forwarded (path preferred; binary or text-flattened acceptable)
Stretch — vendor-dependent fidelity
- Live tool/command output is streamed (
outputDelta), not just final aggregated output - The vendor's aggregated working-tree diff is surfaced (if provided)
- Generated/viewed media (model-produced or model-viewed images) is mirrored
- Vendor-specific modes (review mode, plan mode, etc.) are mirrored as status
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

