paths

Documentation

Overview

Package paths provides cross-platform path resolution utilities for AI coding assistant configuration directories.

This package abstracts the differences between operating systems and AI assistant platforms (Claude Code, OpenCode, Codex, Gemini CLI) for consistent path resolution across all environments.

XDG Base Directory Compliance

The package wraps github.com/adrg/xdg for cross-platform XDG Base Directory Specification compliance. On Linux and macOS, paths follow XDG conventions (~/.config, ~/.local/share, ~/.cache).

Platform Constants

Use the provided platform constants when calling platform-specific functions:

paths.GlobalConfigDir(paths.PlatformClaude)   // ~/.claude/
paths.GlobalConfigDir(paths.PlatformOpenCode) // ~/.config/opencode/

Platform Configuration Directories

Each AI assistant platform uses different directory structures:

| Platform  | Global Config       | Project Config    | Instructions |
|-----------|---------------------|-------------------|--------------|
| Claude    | ~/.claude/          | .claude/          | CLAUDE.md    |
| OpenCode  | ~/.config/opencode/ | (project root)    | AGENTS.md    |
| Codex     | ~/.codex/           | .codex/           | AGENTS.md    |
| Gemini    | ~/.gemini/          | .gemini/          | GEMINI.md    |

Standard Directory Helpers

Skills and commands follow consistent patterns relative to the global config directory:

paths.SkillDir(platform)   // <GlobalConfigDir>/skills/
paths.CommandDir(platform) // <GlobalConfigDir>/commands/

Error Handling

Functions that accept a platform parameter return empty strings for unknown platforms. Use ValidPlatform to check validity before calling:

if !paths.ValidPlatform(platform) {
    return fmt.Errorf("%w: %s", aixerrors.ErrUnknownPlatform, platform)
}

Index

• Constants
• Variables
• func CacheHome() string
• func CommandDir(platform string) string
• func ConfigHome() string
• func DataHome() string
• func EnsureDir(path string, perm os.FileMode) error
• func GlobalConfigDir(platform string) string
• func Home() string
• func InstructionFilename(platform string) string
• func InstructionsPath(platform, projectRoot string) string
• func MCPConfigPath(platform string) string
• func Platforms() []string
• func ProjectConfigDir(platform, projectRoot string) string
• func ReposCacheDir() string
• func ResolveHome() (string, error)
• func SkillDir(platform string) string
• func ValidPlatform(platform string) bool

Constants

const (
	PlatformClaude   = "claude"
	PlatformOpenCode = "opencode"
	PlatformCodex    = "codex"
	PlatformGemini   = "gemini"
)

Platform identifiers for supported AI coding assistants.

const DefaultDirPerm = 0o700

DefaultDirPerm is the default permission for newly created directories (private).

Variables

var (
	// ErrHomeDirNotFound indicates the user's home directory could not be determined.
	ErrHomeDirNotFound = errors.New("home directory not found")

	// ErrPermissionDenied indicates the operation was rejected due to file system permissions.
	ErrPermissionDenied = errors.New("permission denied")

	// ErrInvalidPath indicates the provided path is malformed or invalid.
	ErrInvalidPath = errors.New("invalid path")
)

Sentinel errors for path resolution.

Functions

func CacheHome

func CacheHome() string

CacheHome returns the XDG cache home directory. On Linux: ~/.cache On macOS: ~/.cache (overrides Library/Caches) On Windows: %LOCALAPPDATA%\cache

func CommandDir

func CommandDir(platform string) string

CommandDir returns the commands directory for a platform. Always returns: <GlobalConfigDir>/commands/

Returns an empty string for unknown platforms.

func ConfigHome

func ConfigHome() string

ConfigHome returns the XDG config home directory. It respects the AIX_CONFIG_DIR environment variable if set. On Linux: ~/.config On macOS: ~/.config (overrides Library/Application Support) On Windows: %LOCALAPPDATA%

func DataHome

func DataHome() string

DataHome returns the XDG data home directory. On Linux: ~/.local/share On macOS: ~/.local/share (overrides Library/Application Support) On Windows: %LOCALAPPDATA%

func EnsureDir

func EnsureDir(path string, perm os.FileMode) error

EnsureDir creates the directory and any necessary parents with specified permissions. If perm is 0, DefaultDirPerm (0700) is used. This function is idempotent; it returns nil if the directory already exists.

func GlobalConfigDir

func GlobalConfigDir(platform string) string

GlobalConfigDir returns the global config directory for a platform.

Platform paths:

• claude: ~/.claude/
• opencode: ~/.config/opencode/
• codex: ~/.codex/
• gemini: ~/.gemini/ (or $XDG_CONFIG_HOME/gemini if set)

Returns an empty string for unknown platforms.

func Home

func Home() string

Home returns the user's home directory. This is a thin wrapper around os.UserHomeDir for consistency. Note: It returns an empty string on error for backward compatibility. Use ResolveHome for proper error handling.

func InstructionFilename

func InstructionFilename(platform string) string

InstructionFilename returns just the instruction filename for a platform, without any path components.

Platform filenames:

• claude: CLAUDE.md
• opencode: AGENTS.md
• codex: AGENTS.md
• gemini: GEMINI.md

Returns an empty string for unknown platforms.

func InstructionsPath

func InstructionsPath(platform, projectRoot string) string

InstructionsPath returns the path to the instructions file.

Platform paths:

• claude: <projectRoot>/CLAUDE.md
• opencode: <projectRoot>/AGENTS.md
• codex: <projectRoot>/AGENTS.md
• gemini: <projectRoot>/GEMINI.md

Returns an empty string for unknown platforms or empty projectRoot.

func MCPConfigPath

func MCPConfigPath(platform string) string

MCPConfigPath returns the MCP config file path for a platform.

Platform paths:

• claude: ~/.claude.json (main user config file, NOT in .claude directory)
• opencode: ~/.config/opencode/opencode.json
• codex: ~/.codex/mcp.json
• gemini: ~/.gemini/settings.toml

Returns an empty string for unknown platforms.

func Platforms

func Platforms() []string

Platforms returns a slice of all supported platform identifiers.

func ProjectConfigDir

func ProjectConfigDir(platform, projectRoot string) string

ProjectConfigDir returns the project-scoped config directory.

Platform paths:

• claude: <projectRoot>/.claude/
• opencode: <projectRoot>/ (root of project)
• codex: <projectRoot>/.codex/
• gemini: <projectRoot>/.gemini/

Returns an empty string for unknown platforms or empty projectRoot.

func ReposCacheDir

func ReposCacheDir() string

ReposCacheDir returns the directory for cached repository clones. Returns: <CacheHome>/aix/repos/

func ResolveHome

func ResolveHome() (string, error)

ResolveHome returns the user's home directory. Returns ErrHomeDirNotFound if the directory cannot be determined.

func SkillDir

func SkillDir(platform string) string

SkillDir returns the skills directory for a platform. Always returns: <GlobalConfigDir>/skills/

Returns an empty string for unknown platforms.

func ValidPlatform

func ValidPlatform(platform string) bool

ValidPlatform returns true if the platform name is recognized.