platform

Documentation

Overview

Package platform contains small OS-conditional helpers used by the rest of ccx: resolving the default Claude Code config directory, locating the ccx state directory, expanding user-supplied paths, detecting the user's shell, and figuring out where Claude Code stores credentials per OS.

Implementation files are split via build tags:

platform.go           common, OS-independent helpers
platform_darwin.go    macOS-specific (keychain credentials)
platform_linux.go     Linux-specific (file credentials, $SHELL parsing)
platform_windows.go   Windows-specific (%USERPROFILE%, PowerShell heuristics)

The public API is identical on every platform. Only the implementation switches. Callers do not need to do their own GOOS checks.

Index

• Variables
• func CCXHome() (string, error)
• func CredentialsPath(configDir string) (string, error)
• func DefaultConfigDir() (string, error)
• func DetectShell() contracts.Shell
• func ExpandPath(p string) (string, error)
• func IsCredentialsInKeychain() bool
• func ProcessAlive(pid int) bool
• func ProcessIdentity(pid int) (string, bool)
• func ProcessMatches(pid int, expectedExecutable string) bool
• func StartDetachedProcess(ctx context.Context, spec *DetachedProcessSpec) (int, error)
• func TerminateProcess(pid int) error
• type DetachedProcessSpec
• type OSProcessManager
  • func (OSProcessManager) Alive(pid int) bool
  • func (OSProcessManager) Matches(pid int, expectedExecutable string) bool
  • func (OSProcessManager) StartDetached(ctx context.Context, spec *DetachedProcessSpec) (int, error)
  • func (OSProcessManager) Terminate(pid int) error

Variables

var ErrCredentialsInKeychain = errors.New("credentials stored in macOS Keychain, no file path")

ErrCredentialsInKeychain is returned by CredentialsPath on macOS, where Claude Code stores credentials in the system Keychain rather than on disk. Callers should detect this with errors.Is and skip file-based credential checks.

Functions

func CCXHome

func CCXHome() (string, error)

CCXHome returns the ccx state directory (~/.ccx on Unix, %USERPROFILE%\.ccx on Windows). The directory is created with 0700 permissions if it does not already exist.

func CredentialsPath

func CredentialsPath(configDir string) (string, error)

CredentialsPath returns the credentials file path for the given Claude Code config directory. On macOS the credentials live in the Keychain and this function returns ("", ErrCredentialsInKeychain); callers should detect that with errors.Is.

func DefaultConfigDir

func DefaultConfigDir() (string, error)

DefaultConfigDir returns the platform-default Claude Code config directory.

macOS:   $HOME/.claude (or $HOME/.config/claude if that exists)
Linux:   $HOME/.claude (or $HOME/.config/claude if that exists)
Windows: %USERPROFILE%\.claude

If CLAUDE_CONFIG_DIR is set in the environment, its value (after path expansion) is returned instead. The returned path is absolute but may not yet exist on disk.

func DetectShell

func DetectShell() contracts.Shell

DetectShell returns the user's current shell, inferring from $SHELL on Unix and from $PSModulePath (or parent shell hints) on Windows. Returns contracts.ShellUnknown when it cannot decide.

func ExpandPath

func ExpandPath(p string) (string, error)

ExpandPath expands a leading "~" (and only a leading "~") to the current user's home directory, then expands environment variables via os.ExpandEnv, and finally returns an absolute, clean path.

Examples (with HOME=/Users/arafa):

"~/foo"          -> "/Users/arafa/foo"
"$HOME/foo"      -> "/Users/arafa/foo"
"./relative"     -> "<cwd>/relative"
"/abs"           -> "/abs"

"~user" syntax is not supported (just like Go's filepath stdlib).

func IsCredentialsInKeychain

func IsCredentialsInKeychain() bool

IsCredentialsInKeychain reports whether the current OS stores Claude Code credentials in the system keychain (true on darwin) rather than on disk (false on linux/windows).

func ProcessAlive

func ProcessAlive(pid int) bool

ProcessAlive reports whether pid currently belongs to a live process.

func ProcessIdentity

func ProcessIdentity(pid int) (string, bool)

ProcessIdentity returns a stable identity for the currently running process occupying pid. The value is suitable only for equality checks within the same machine boot and should not be shown to users.

func ProcessMatches

func ProcessMatches(pid int, expectedExecutable string) bool

ProcessMatches reports whether pid appears to be running expectedExecutable.

func StartDetachedProcess

func StartDetachedProcess(ctx context.Context, spec *DetachedProcessSpec) (int, error)

StartDetachedProcess starts spec as a user process detached from the current ccx invocation and returns the child pid.

func TerminateProcess

func TerminateProcess(pid int) error

TerminateProcess asks pid to exit gracefully where the platform supports it.

Types

type DetachedProcessSpec

type DetachedProcessSpec struct {
	Executable string
	Args       []string
	Env        []string
	LogPath    string
}

DetachedProcessSpec describes a child process that should outlive ccx.

type OSProcessManager

type OSProcessManager struct{}

OSProcessManager provides the process operations needed by daemon lifecycle commands.

func (OSProcessManager) Alive

func (OSProcessManager) Alive(pid int) bool

Alive reports whether pid currently belongs to a live process.

func (OSProcessManager) Matches

func (OSProcessManager) Matches(pid int, expectedExecutable string) bool

Matches reports whether pid appears to be running expectedExecutable.

func (OSProcessManager) StartDetached

func (OSProcessManager) StartDetached(ctx context.Context, spec *DetachedProcessSpec) (int, error)

StartDetached starts spec as a user process detached from the current ccx invocation and returns the child pid.

func (OSProcessManager) Terminate

func (OSProcessManager) Terminate(pid int) error

Terminate asks pid to exit gracefully where the platform supports it.