Documentation
¶
Overview ¶
Package setup handles agent plugin installation.
- OpenCode: copies embedded plugin file to ~/.config/opencode/plugins/ (patching ENGRAM_BIN to bake in the absolute binary path as a final fallback) and injects MCP registration in opencode.json using the resolved absolute binary path so child processes never require PATH resolution in headless/systemd environments.
- Claude Code: runs `claude plugin marketplace add` + `claude plugin install`, then asks Claude CLI to register a durable user-scope stdio MCP server using the resolved absolute binary path.
- Gemini CLI: injects MCP registration in ~/.gemini/settings.json
- Codex: injects MCP registration in ~/.codex/config.toml
- Pi: installs the gentle-engram package; native tools own Engram writes
Index ¶
- Constants
- func AddClaudeCodeAllowlist() error
- func ClaudeCodeSettingsPath() string
- func ClaudeCodeUserMCPPath() string
- func EnsureClaudeCodeUserMCP() error
- func PostInstallSteps(agent string) []string
- func ReadProtocolMode(dataDir, slug string) string
- func VerifyClaudeCodeSlimCapability() error
- func WriteProtocolMode(dataDir, slug, mode string) error
- type Agent
- type Result
- type StaleMCPCommand
Constants ¶
const ( ProtocolModeSlim = "slim" ProtocolModeFull = "full" )
Protocol mode values persisted per setup slug. A slug's mode controls how verbose the version-pinned Claude Code hook scripts render the ACTIVE PROTOCOL prose at session start / post-compaction.
Variables ¶
This section is empty.
Functions ¶
func AddClaudeCodeAllowlist ¶
func AddClaudeCodeAllowlist() error
AddClaudeCodeAllowlist adds engram MCP tool names to ~/.claude/settings.json permissions.allow so Claude Code doesn't prompt for confirmation on each call. Idempotent: skips tools already present in the list.
func ClaudeCodeSettingsPath ¶
func ClaudeCodeSettingsPath() string
ClaudeCodeSettingsPath returns the path to Claude Code's user-level settings.json file (see claudeCodeConfigRoot).
func ClaudeCodeUserMCPPath ¶
func ClaudeCodeUserMCPPath() string
ClaudeCodeUserMCPPath returns the Claude Code user configuration file that contains the top-level mcpServers object. Claude CLI owns all writes to it.
func EnsureClaudeCodeUserMCP ¶
func EnsureClaudeCodeUserMCP() error
EnsureClaudeCodeUserMCP registers an absent user-scope server through Claude CLI, verifies it by re-reading Claude's config, and never overwrites a pre-existing registration.
func PostInstallSteps ¶
PostInstallSteps returns the human-facing "next steps" lines for an agent, or nil when the agent's post-install messaging is handled specially by the CLI (opencode's conditional TUI note, claude-code's interactive allowlist prompt).
func ReadProtocolMode ¶
ReadProtocolMode returns the persisted protocol mode for slug inside dataDir. It defaults to ProtocolModeFull whenever the mode cannot be resolved with certainty: missing file, unreadable file, malformed JSON, or no entry for slug. This keeps every failure mode safe (never silently suppresses the protocol prose).
func VerifyClaudeCodeSlimCapability ¶
func VerifyClaudeCodeSlimCapability() error
VerifyClaudeCodeSlimCapability confirms that the installed marketplace plugin has the hook guard required for the slim protocol. Claude Code does not promise a complete JSON schema, so only known array and {"plugins": [...]} shapes are accepted; an unfamiliar response remains unverified.
func WriteProtocolMode ¶
WriteProtocolMode upserts slug's mode into dataDir's mode file, preserving entries for other slugs. Unknown or empty mode values normalize to ProtocolModeFull rather than failing — persistence itself never fails `engram setup` (callers may still surface a warning for unknown input).
A missing file starts fresh. A file that exists but fails to parse (corrupted) is NOT silently treated as "start fresh" — that would overwrite whatever other slugs' modes it might still contain with a single-entry file, compounding the data loss. Instead the write is refused and an error is returned so the caller can warn and leave the file for manual inspection/recovery (the read path still degrades to ProtocolModeFull for any unparseable file, as before).
Types ¶
type Agent ¶
type Agent struct {
Name string
Description string
InstallDir string // resolved at runtime (display only for claude-code)
}
Agent represents a supported AI coding agent.
func SupportedAgents ¶
func SupportedAgents() []Agent
SupportedAgents returns the list of agents that have plugins available. The list is derived from the registry (agentAdapters) so adding an agent there surfaces it here and in `engram setup --help` automatically.
type Result ¶
type Result struct {
Agent string
Destination string
Files int
MCPConfigured bool
TUIPluginEnabled bool
}
Result holds the outcome of an installation.
type StaleMCPCommand ¶
StaleMCPCommand identifies a generic client registration pointing to a missing binary.
func StaleMCPCommands ¶
func StaleMCPCommands() ([]StaleMCPCommand, error)
StaleMCPCommands inspects only existing generic Engram registrations without executing the configured command or modifying client configuration.
Source Files