appdir

Documentation

Overview

Package appdir decides where magpie keeps its own files: the one place every other package asks (#508).

Installed, that is ~/.config/magpie ($XDG_CONFIG_HOME/magpie) for what magpie keeps and ~/.cache/magpie ($XDG_CACHE_HOME/magpie) for what it can fetch again, as it always was. Portable, when a folder named "data" (or a file named ".portable") sits beside magpie, everything magpie keeps goes into that data folder, its caches into data/cache and the Windows webview's profile into data/webview2 (no Start-menu shortcut or App Paths entry is made either), and nothing of magpie's own is written to the user's profile, the way VS Code's portable mode works. "Beside magpie" is the folder holding the executable, with links followed; for a Mac app it is the folder holding Magpie.app (a file put inside the bundle would break its signature), and for an AppImage the folder holding the .AppImage file, not the folder it is mounted at while it runs.

What isn't magpie's own stays where its owner reads it: the agents' configs (~/.claude, ~/.codex…), the sign-ins they keep in the system keychain, the folders the OS reads for autostart and link handling, and temporary folders.

A data folder in a folder every app or download shares (/Applications on a Mac; the home folder, Downloads, Desktop and Documents everywhere) is taken for magpie's own only when it already holds magpie's files and the installed folder doesn't, or with a ".portable" marker: a "data" folder there is as likely another app's or the user's own. Taking one showed a user who had never asked for portable an empty magpie (#989), and wrote magpie's files into a Downloads\data folder a Windows user's archiver empties, so a provider just added was gone (tangle778 on X).

The decision is made once, from the executable as it was when magpie started: an update moving the running copy aside (into .magpie-update on a Mac, to magpie.exe.old on Windows) leaves it running from somewhere else, and its files must not move with it.

Index

• Constants
• func Beside(exe string) string
• func Cache() string
• func CheckEnv() (ignored []string, err error)
• func ClaudeDir() string
• func ClaudeDirIn(home string) string
• func CodexHome() string
• func CodexHomeIn(home string) string
• func Config() string
• func Getenv(name string) string
• func HermesDefaultIn(home string) string
• func HermesHome() string
• func HermesHomeIn(home string) string
• func Home() (string, error)
• func LookupEnv(name string) (string, bool)
• func Passed(exe string) string
• func Portable() string
• func Redirected() string
• func Resolve(exe string) string
• func SystemCache() (string, error)
• func UseExecutable(exe string)
• func WebView() string
• func ZCodeDataIn(home string) string

Constants

const (
	// DataName is the folder beside magpie that makes it portable and
	// holds its files.
	DataName = "data"
	// MarkerName is a file beside magpie that makes it portable too, its
	// files then going into a data folder made beside it.
	MarkerName = ".portable"
)

Functions

func Beside

func Beside(exe string) string

Beside is the folder a portable magpie run from exe keeps its data folder in: the executable's own, the one holding the .app on a Mac, the one holding the .AppImage on Linux. APPIMAGE counts only for the AppImage magpie runs from (exe under its mount, APPDIR): every program an AppImage starts inherits both, a magpie started from an AppImage terminal too.

func Cache

func Cache() string

Cache is the folder for what magpie can fetch again (the models.dev catalog, exchange rates, market lists).

func CheckEnv

func CheckEnv() (ignored []string, err error)

CheckEnv is what main checks before anything is read or written: an unusable home folder is the error, and ignored names the folder variables holding a relative path, which LookupEnv passes over.

func ClaudeDir

func ClaudeDir() string

ClaudeDir is the folder Claude Code keeps its files in: settings.json, the credentials it keeps off a keychain, history, sessions, skills. It is $CLAUDE_CONFIG_DIR when that is set, as Claude Code reads it, else ~/.claude. Every place magpie reads or writes Claude Code's files goes through here: the Agents page's wiring once wrote ~/.claude/settings.json and looked for ~/.claude alone while the sessions, the library and the sign-in read $CLAUDE_CONFIG_DIR, so a Claude Code kept there wasn't listed and a model picked for it went to a file it never read (#1482). It is read through LookupEnv, so the value a login shell lends the desktop app (proc.UserPath) counts, and a relative one reads as unset.

func ClaudeDirIn

func ClaudeDirIn(home string) string

ClaudeDirIn is ClaudeDir with home as the user's home folder.

func CodexHome

func CodexHome() string

CodexHome is the folder Codex CLI keeps its files in: config.toml, auth.json, the model catalog magpie writes, sessions, AGENTS.md and skills. It is $CODEX_HOME when that is set, as codex-rs's find_codex_home reads it, else ~/.codex. Every place magpie reads or writes Codex's files goes through here (Wakkana on Discord: with CODEX_HOME set, a model picked in magpie went to ~/.codex/config.toml, which Codex never read). CODEX_HOME is read through LookupEnv, so the value a login shell lends the desktop app (proc.UserPath) counts, and a relative one, which Codex would take from whatever folder it runs in, reads as unset.

func CodexHomeIn

func CodexHomeIn(home string) string

CodexHomeIn is CodexHome with home as the user's home folder.

func Config

func Config() string

Config is the folder magpie keeps its settings, providers, usage and the rest of its own state in.

func Getenv

func Getenv(name string) string

Getenv is LookupEnv's value, "" for a variable unset or ignored.

func HermesDefaultIn

func HermesDefaultIn(home string) string

HermesDefaultIn is Hermes's own default home on this machine, whatever HERMES_HOME says (hermes_constants._get_platform_default_hermes_home): the root a HERMES_HOME under it is a profile of.

func HermesHome

func HermesHome() string

HermesHome is the folder Hermes Agent (Nous Research) keeps its files in: config.yaml, .env, plugins, skills, profiles and state.db. It is $HERMES_HOME when that is set, else the platform's default, as hermes_constants.get_hermes_home reads them: %LOCALAPPDATA%\hermes on Windows (AppData\Local\hermes under the home folder without LOCALAPPDATA), ~/.hermes everywhere else. Every place magpie reads or writes Hermes's files goes through here (新v学员 on Discord: on native Windows Hermes and rtk's hook were in %LOCALAPPDATA%\hermes, and magpie looked for them in ~/.hermes).

func HermesHomeIn

func HermesHomeIn(home string) string

HermesHomeIn is HermesHome with home as the user's home folder.

func Home

func Home() (string, error)

Home is the user's home folder, or an error when its variable is unset, empty or relative. os.UserHomeDir hands back "" there, which filepath.Join turns into a path under the folder magpie was started in, and on Android it falls back to the shared /sdcard.

func LookupEnv

func LookupEnv(name string) (string, bool)

LookupEnv is os.LookupEnv for what magpie itself reads: a folder variable (pathVars) holding a relative path reads as unset, as the XDG spec asks of one, so no file of magpie's or an agent's is written under the working folder. The environment is left as it is: the programs magpie starts get the variable as the user set it. The variables a login shell lends the desktop app (proc.UserPath) are read through here too.

func Passed

func Passed(exe string) string

Passed is the data folder beside a magpie run from exe that holds magpie's files but that Resolve doesn't take for its own, because it is in a shared folder while the installed folder has magpie's files too, or "". A data folder holding none of them is someone else's and isn't named.

func Portable

func Portable() string

Portable is the data folder magpie keeps everything in, or "" when it isn't portable.

func Redirected

func Redirected() string

Redirected is the folder magpie keeps its files in when it is opened from the Dock, the Start menu or a desktop launcher (~/.config/magpie), while this magpie reads them from another that XDG_CONFIG_HOME, set in the shell it was run from, names; "" when they are the same, or magpie is portable. A magpie run in such a shell sees none of what the app's window shows.

func Resolve

func Resolve(exe string) string

Resolve is the data folder of a magpie run from exe, or "" when it isn't portable.

func SystemCache

func SystemCache() (string, error)

SystemCache is the cache folder the OS names for magpie (~/Library/Caches/magpie on a Mac, %LocalAppData%\magpie on Windows), which a few caches have always used; portable, it is Cache.

func UseExecutable

func UseExecutable(exe string)

UseExecutable decides again as if magpie ran from exe ("" for an installed magpie, whatever runs): for tests.

func WebView

func WebView() string

WebView is the folder the Windows webview (WebView2) keeps its profile in — its cache, cookies and the pages' storage — or "" for its own default. Installed, that default is %APPDATA%\<exe name>, as it always was, so nothing kept there is lost; portable, it is data\webview2, so a portable magpie leaves no magpie.exe folder in the user's AppData (#508).

func ZCodeDataIn

func ZCodeDataIn(home string) string

ZCodeDataIn is the folder ZCode (Zhipu's desktop app) keeps its .zcode data in, with home as the user's home folder: the home folder, unless the user moved it in ZCode's settings (数据存储路径, "data storage path"). ZCode then copies its .zcode/v2 there and reads it from there from its next start, providers (provider_config.json, config.json) and sign-in (credentials.json) included; the choice stays in the home folder's .zcode/v2/setting.json as dataBaseDir, which ZCode's main process reads before anything else (readBootstrapDataBaseDirFromDisk). A value that isn't an absolute path is ignored, as Getenv ignores one.

Skills, AGENTS.md and the CLI's config.json stay under the home folder whatever this says: ZCode reads those from HOME/USERPROFILE.