synheart guard
Hold your coding agents to rules you set
Checks what a coding agent is about to do (push, merge, delete, deploy,
edit a protected file) against rules you wrote, before it runs. A rule either
asks you or stops the agent. Exceptions are scoped to a repository, branch or
path, expire after the time you set, and can only be granted by you at a
terminal.
Everything stays on this machine: your rules in ~/.synheart/guard/rules.yaml, a
repository’s own rules in .synheart/guard.yaml, and a local log of which rules
fired (never the commands themselves). Start with ‘synheart guard init’, then
‘synheart guard install’ to hook it into Claude Code.
Usage
synheart guard allow: Allow a blocked action for a limited timesynheart guard check: Test a shell command against your guard rulessynheart guard init: Create your guard rules filesynheart guard install: Hook the guard into Claude Codesynheart guard report: Summarise what the guard stopped, asked and allowedsynheart guard rules: List the guard rules in force heresynheart guard sync: Refresh team rules and upload day totals nowsynheart guard team: Use your organization’s guard rules
synheart guard allow
Allow a blocked action for a limited time
Lets what a rule stops or asks about through, in the scope you give and
only until the time you set (default 1h, at most 168h). Use it when you know a
one-off action is fine. Only you can run it, at a terminal; an agent cannot.
Find rule IDs with ‘synheart guard rules’. Scope the exception with —repo,
—branch or —path; without them it applies everywhere.
Usage
Examples
synheart guard check
Test a shell command against your guard rules
Shows what the guard would do with a shell command in the current
directory, without running it: stop, ask, or let it through, and which rule
decided. Everything after ‘check’ is the command to test, flags included, except
a trailing —json, which prints the actions, verdict and matching rules as an
object. Needs no login and no network.
Usage
--json (or --format json) to print a machine-readable body.
synheart guard init
Create your guard rules file
Writes ~/.synheart/guard/rules.yaml, from a starter set or from a file you
give with —from, and checks that it loads. Refuses to overwrite an existing
file. Only you can run it, at a terminal. Next step: ‘synheart guard install’.
Usage
Examples
synheart guard install
Hook the guard into Claude Code
Without flags, prints the Claude Code settings that run the guard before and
after each action. With —write, merges them into ~/.claude/settings.json, or
into .claude/settings.local.json in this directory with —project. It keeps
every other setting and hook, saves a backup first, and changes nothing when
run again.
Usage
Examples
synheart guard report
Summarise what the guard stopped, asked and allowed
Counts how often each rule fired over a period: stopped, asked, or let
through. It reads the local log, which never holds commands or file paths. With
—json it prints the counts as an object. Needs no login and no network.
Usage
Examples
--json (or --format json) to print a machine-readable body.
synheart guard rules
List the guard rules in force here
Lists the rules that apply in the current directory, merged from your
rules file, the repository’s .synheart/guard.yaml and your team’s rules, each
with its verdict (stop or ask; “shadow” means it only logs). Active exceptions
follow. With —json it prints an object with the rules under “items” and the
active exceptions under “exceptions”. Needs no login and no network.
Usage
--json (or --format json) to print a machine-readable body.
synheart guard sync
Refresh team rules and upload day totals now
Fetches your organization’s current rules from Synapse and uploads the day
totals of which rules fired, never commands, paths or prompts. The guard does
this in the background about every 15 minutes; run it to do it now. Needs: you
joined a team (‘synheart guard team join’) and network access.
Usage
Examples
synheart guard team
Use your organization’s guard rules
Applies your organization’s rules from Synapse on this machine, ahead of
your own, and shares day totals of which rules fired with your team. Never a
command, a file path or a prompt. Use ‘join’ to start, ‘status’ to check, and
‘leave’ to stop.
Usage
synheart guard team join: Enforce your organization’s agent rules heresynheart guard team leave: Stop using your organization’s rules heresynheart guard team status: Show your guard team and last sync
synheart guard team join
Enforce your organization’s agent rules here
Fetches your organization’s rules from Synapse and enforces them ahead of
your own, then runs a first sync. Day totals of which rule fired (stopped,
asked, let through) are shared with your team, never a command, a file path or a
prompt. Only you can run it, at a terminal.
Needs: you are logged in (‘synheart login’) and network access. The
organization comes from your sign-in unless you pass —org.
Usage
Examples
synheart guard team leave
Stop using your organization’s rules here
Removes your organization’s rules and the team link from this machine. Your
own rules keep applying. Only you can run it, at a terminal. Needs no network.
Usage
synheart guard team status
Show your guard team and last sync
Shows the organization this machine takes rules from, the policy version,
when it last synced, and the last sync error if there was one. Says “not in a
team” when you have not joined. With —json it prints the same as an object.
Reads local state only.
Usage
--json (or --format json) to print a machine-readable body.
synheart mcp
Connect AI agents through the MCP server
Exposes the Synheart CLI to AI agents (Claude Code, Cursor, Claude Desktop)
through the Model Context Protocol, so they can call its read-only commands as
tools. ‘synheart mcp’ on its own prints this help.
Add ‘synheart mcp serve’ to your agent’s MCP server list to use it. See
docs/cli-mcp.md for the setup of each client.
Usage
synheart mcp serve: Run the MCP server on stdin and stdout
synheart mcp serve
Run the MCP server on stdin and stdout
Reads JSON-RPC 2.0 messages from stdin, one per line, and writes responses
to stdout. The server is read-only: it offers explain, doctor, config show,
auth status, whoami and list-scenarios, and never signs in or changes anything
on the agent’s behalf.
An MCP client starts this command; it prints nothing until the client sends a
request. Needs no network of its own.
Usage
synheart syni
Chat with Syni, Synheart’s state-aware assistant
Syni is Synheart’s state-aware conversational layer. Run ‘synheart syni’
in a terminal to chat interactively; use the subcommands for one-shot messages,
personas and past sessions.
Cloud chat needs you to be logged in and a plan that includes it (see
‘synheart usage’). Without a terminal, or with —json or —no-repl, running
‘synheart syni’ prints this help instead. Pass —org, —tenant or —project (or
the matching SYNHEART_*_ID variables) to choose the scope.
Usage
Subcommands
synheart syni chat: Send a message to Synisynheart syni personas: List Syni personassynheart syni sessions: Inspect Syni chat sessionssynheart syni version: Show installed syni-spec and syni-runtime versions
synheart syni chat
Send a message to Syni
Sends a message to Syni in the cloud and prints the reply. With a message
it runs once and exits; with none, in a terminal, it opens an interactive chat.
Pass a persona ID first to talk to a specific persona, and —session to continue
an earlier conversation. Use —no-repl to require a message.
Needs: you are logged in, a plan that includes cloud chat, and network access.
With —json it prints the reply as an object.
Usage
Examples
--json (or --format json) to print a machine-readable body.
synheart syni personas
List Syni personas
Lists the personas you can chat with, each with its ID. Use an ID with
‘synheart syni chat <persona>’. Needs: you are logged in, network access and a
project ID (—project, SYNHEART_PROJECT_ID, or platform.project in
.synheart/config.yaml). With —json it prints the list.
Usage
synheart syni personas show: Show one Syni persona
--json (or --format json) to print a machine-readable body.
synheart syni personas show
Show one Syni persona
Prints the details of the persona with the given ID. Needs you to be
logged in and network access. With —json it prints the persona as an object.
Usage
--json (or --format json) to print a machine-readable body.
synheart syni sessions
Inspect Syni chat sessions
Work with your Syni chat sessions. Use ‘synheart syni sessions show’ to
read one, and pass its ID to ‘synheart syni chat —session’ to continue it.
Usage
synheart syni sessions show: Show a Syni session and its messages
synheart syni sessions show
Show a Syni session and its messages
Prints a chat session and its messages. Needs you to be logged in and
network access. With —json it prints the session as an object.
Usage
--json (or --format json) to print a machine-readable body.
synheart syni version
Show installed syni-spec and syni-runtime versions
Prints the versions of the syni-spec and syni-runtime packages installed in
the current project. It reads the vendored packages, or the pins in
synheart.lock when they are not vendored yet; “source” in the JSON says which.
Reads local files only, so it needs no login and no network.
Usage
--json (or --format json) to print a machine-readable body.