Documentation
¶
Overview ¶
Package claude provides Claude Code integration templates and utilities.
It embeds hook scripts, slash command definitions, and configuration types for integrating ctx with Claude Code's settings.local.json. The embedded assets are installed to project directories via "ctx init --claude".
Embedded assets:
- auto-save-session.sh: Saves session transcripts on session end
- block-non-path-ctx.sh: Prevents non-PATH ctx invocations
- tpl/commands/*.md: Slash command definitions for Claude Code
Example usage:
script, err := claude.AutoSaveScript()
if err != nil {
return err
}
os.WriteFile(".claude/hooks/auto-save-session.sh", script, 0755)
Index ¶
- func AutoSaveScript() ([]byte, error)
- func BlockNonPathCtxScript() ([]byte, error)
- func CheckContextSizeScript() ([]byte, error)
- func PromptCoachScript() ([]byte, error)
- func SkillContent(name string) ([]byte, error)
- func Skills() ([]string, error)
- type Hook
- type HookConfig
- type HookMatcher
- type HookType
- type Matcher
- type PermissionsConfig
- type Settings
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AutoSaveScript ¶ added in v0.2.0
AutoSaveScript returns the auto-save session script content.
The script automatically saves Claude Code session transcripts when a session ends. It is installed to .claude/hooks/ during ctx init --claude.
Returns:
- []byte: Raw bytes of the auto-save-session.sh script
- error: Non-nil if the embedded file cannot be read
func BlockNonPathCtxScript ¶ added in v0.2.0
BlockNonPathCtxScript returns the script that blocks non-PATH ctx invocations.
The script prevents Claude from running ctx via relative paths (./ctx, ./dist/ctx) or "go run", ensuring only the installed PATH version is used. It is installed to .claude/hooks/ during ctx init --claude.
Returns:
- []byte: Raw bytes of the block-non-path-ctx.sh script
- error: Non-nil if the embedded file cannot be read
func CheckContextSizeScript ¶ added in v0.3.0
CheckContextSizeScript returns the context size checkpoint hook script.
The script counts prompts per session and outputs adaptive reminders to stderr, prompting Claude to assess remaining context capacity. Frequency increases as the session grows (silent for first 15 prompts, then every 5th, then every 3rd).
Returns:
- []byte: Raw bytes of the check-context-size.sh script
- error: Non-nil if the embedded file cannot be read
func PromptCoachScript ¶ added in v0.2.0
PromptCoachScript returns the prompt coaching hook script.
The script detects prompt antipatterns (e.g., "idiomatic Go") and suggests better alternatives (e.g., "follow project conventions"). It limits suggestions to 3 per pattern per session to avoid annoying the user. It is installed to .claude/hooks/ during ctx init --claude.
Returns:
- []byte: Raw bytes of the prompt-coach.sh script
- error: Non-nil if the embedded file cannot be read
func SkillContent ¶ added in v0.3.0
SkillContent returns the content of a skill's SKILL.md file by name.
Parameters:
- name: Skill directory name as returned by Skills (e.g., "ctx-status")
Returns:
- []byte: Raw bytes of the SKILL.md file
- error: Non-nil if the skill does not exist or cannot be read
func Skills ¶ added in v0.3.0
Skills returns the list of embedded skill directory names.
These are Agent Skills (https://agentskills.io) following the specification with SKILL.md files containing frontmatter (name, description) and autonomy-focused instructions. They can be installed to .claude/skills/ via "ctx init".
Returns:
- []string: Names of available skill directories (e.g., "ctx-status", "ctx-save")
- error: Non-nil if the skills directory cannot be read
Types ¶
type Hook ¶
Hook represents a single hook command to execute.
Fields:
- Type: Hook type, typically "command"
- Command: Shell command or script path to execute
type HookConfig ¶
type HookConfig struct {
PreToolUse []HookMatcher `json:"PreToolUse,omitempty"`
UserPromptSubmit []HookMatcher `json:"UserPromptSubmit,omitempty"`
SessionEnd []HookMatcher `json:"SessionEnd,omitempty"`
}
HookConfig represents the hooks section of Claude Code's settings.local.json.
Hooks are shell commands that Claude Code executes at specific lifecycle events. See https://docs.anthropic.com/en/docs/claude-code/hooks for details.
Fields:
- PreToolUse: Matchers that run before each tool invocation
- UserPromptSubmit: Matchers that run when the user submits a prompt
- SessionEnd: Matchers that run when a session ends
func DefaultHooks ¶ added in v0.2.0
func DefaultHooks(projectDir string) HookConfig
DefaultHooks returns the default ctx hooks configuration for Claude Code.
The returned hooks configure PreToolUse to block non-PATH ctx invocations and autoload context on every tool use, UserPromptSubmit for prompt coaching, and SessionEnd to run auto-save-session.sh for persisting session transcripts.
Parameters:
- projectDir: Project root directory for absolute hook paths; if empty, paths are relative (e.g., ".claude/hooks/")
Returns:
- HookConfig: Configured hooks for PreToolUse, UserPromptSubmit, and SessionEnd events
type HookMatcher ¶
HookMatcher associates a regex pattern with hooks to execute.
For PreToolUse hooks, the Matcher pattern matches against the tool name (e.g., "Bash", "Read"). Use ".*" to match all tools.
Fields:
- Matcher: Regex pattern to match; empty string matches all
- Hooks: Commands to execute when the pattern matches
type Matcher ¶ added in v0.3.0
type Matcher string
var MatcherAll Matcher = ".*"
var MatcherBash Matcher = "Bash"
type PermissionsConfig ¶ added in v0.1.2
type PermissionsConfig struct {
Allow []string `json:"allow,omitempty"`
}
PermissionsConfig represents the permissions section of Claude Code's settings.local.json.
Fields:
- Allow: List of tool patterns that are pre-approved (e.g., "Bash(ctx status:*)")
type Settings ¶
type Settings struct {
Hooks HookConfig `json:"hooks,omitempty"`
Permissions PermissionsConfig `json:"permissions,omitempty"`
}
Settings represents the full Claude Code settings.local.json structure.
This is used when reading or writing project-level Claude Code configuration.
Fields:
- Hooks: Hook configuration for lifecycle events
- Permissions: Tool permission configuration
Source Files