discover

Documentation

Overview

Package discover locates agent-configuration artifacts belonging to Claude Code and Kiro CLI, in both the user (home) and workspace scopes.

It only reads metadata: paths, kinds, and whether an entry is a symlink. Translation and writing live in other packages so that discovery stays safe to run anywhere, including against directories you do not own.

Index

• type Artifact
  • func Scan(l Layout) ([]Artifact, error)
  • func (a Artifact) SharedLink(sharedRoot string) bool
• type Harness
• type Kind
• type Layout
  • func DefaultLayout(workspace string) (Layout, error)
• type Scope

Types

type Artifact

type Artifact struct {
	Path       string
	Harness    Harness
	Kind       Kind
	Scope      Scope
	IsSymlink  bool
	LinkTarget string // resolved target when IsSymlink is true
	SizeBytes  int64
}

Artifact is a single configuration file discovered on disk.

func Scan

func Scan(l Layout) ([]Artifact, error)

Scan walks every known location and returns the artifacts that exist. Missing paths are not errors; they are the normal case.

func (Artifact) SharedLink

func (a Artifact) SharedLink(sharedRoot string) bool

SharedLink reports whether the artifact is a symlink pointing into the shared root (~/.agents). Shared artifacts need no translation: both harnesses already read the same bytes.

Both sides are canonicalised first. On macOS a home or temp directory may itself sit behind a symlink (/var -> /private/var), in which case the resolved link target and the raw shared root would otherwise never match.

type Harness

type Harness string

Harness identifies which tool an artifact belongs to.

const (
	ClaudeCode Harness = "claude-code"
	KiroCLI    Harness = "kiro-cli"
	Shared     Harness = "shared"
)

The harnesses kirobuff knows how to read.

type Kind

type Kind string

Kind classifies an artifact by the role it plays, independent of harness. Two artifacts with the same Kind are candidates for translation.

const (
	KindMemory   Kind = "memory"   // CLAUDE.md, AGENTS.md, steering files
	KindCommand  Kind = "command"  // .claude/commands/*.md, .kiro/prompts/*.md
	KindAgent    Kind = "agent"    // subagent / agent definitions
	KindSkill    Kind = "skill"    // SKILL.md with YAML frontmatter
	KindSettings Kind = "settings" // settings.json, cli.json
	KindMCP      Kind = "mcp"      // MCP server declarations
)

The artifact roles, independent of harness.

type Layout

type Layout struct {
	Home       string // user home
	Workspace  string // current project root, may be empty
	ClaudeHome string // default: <Home>/.claude
	KiroHome   string // default: <Home>/.kiro, or $KIRO_HOME
	SharedRoot string // default: <Home>/.agents
}

Layout describes where each harness keeps its files. Overridable so tests can run against a temp dir and so KIRO_HOME is respected.

func DefaultLayout

func DefaultLayout(workspace string) (Layout, error)

DefaultLayout builds a Layout from the environment.

type Scope

type Scope string

Scope distinguishes user-level from workspace-level configuration.

const (
	ScopeUser      Scope = "user"
	ScopeWorkspace Scope = "workspace"
)

Configuration scopes.