Skip to content
claudewheel.profile
Updated Edit
On this page

Standalone profile resolution for programmatic callers.

#claudewheel.profile

#claudewheel.profile

Resolve a profile name to its launch environment (see ProfileStore.env).

This module is a thin facade over the workspace stores (:class:claudewheel.workspace.Workspace). Its single public function, :func:resolve_profile, maps a profile name to the environment variables Claude Code needs at launch.

  • Workspace root: the CLAUDEWHEEL_CONFIG_DIR environment variable when

set (expanduser'd), otherwise ~/.claudewheel. The root is the only knob; everything else is derived from it. A caller that owns its own workspace passes it as the workspace keyword argument instead, and no environment variable is consulted.

  • Profile locations are derived from directories, never persisted: the set

of profiles is the profiles/ directory scan plus the built-in ~/.claude default. No options.json metadata is consulted.

  • Zero filesystem writes, no terminal I/O -- safe on read-only mounts and

headless servers.

All resolution work lives in :meth:claudewheel.profile_store.ProfileStore.env; this module only picks the workspace -- the default one, or the one the caller injected -- and delegates.

#resolve_profile

python
def resolve_profile(name: str, *, workspace: Workspace | None=None) -> dict[str, str]

Resolve a profile name to its launch environment variables.

For a named profile the result is the profile-owned launch environment that :meth:claudewheel.profile_store.ProfileStore.env defines (the config dir, the stored token when one exists, and the quieting switches; that method's docstring is the one list). The "default" profile is the exception: it is Claude Code's own ~/.claude (managed by Claude Code, read-only to cw), so it resolves to an EMPTY dict (the vanilla path).

Contract:

  • Unknown profile -> :class:ValueError whose message lists the

available profile names.

  • Corrupt or unreadable token entry ->

:class:~claudewheel.tokens.TokenStoreError (a hard error). A profile with no stored token entry at all is NOT an error -- resolution succeeds, simply without a token.

  • Profiles are resolved purely from the on-disk workspace layout: the

profiles/ directory scan plus the built-in ~/.claude default, and each profile's token comes from its own claudewheel data directory. Profile locations are derived from directories, never persisted; options.json metadata is no longer consulted (a deliberate contract change from earlier versions).

  • The workspace root is chosen by the caller through the workspace

parameter, or -- when it is omitted or None -- by :meth:Workspace.default: the CLAUDEWHEEL_CONFIG_DIR environment variable when set (expanduser'd), otherwise ~/.claudewheel.

  • Zero filesystem writes, zero terminal I/O -- safe for read-only mounts

and headless servers.

workspace is the injection seam for library consumers and their test isolation: pass a :class:~claudewheel.workspace.Workspace (built with :meth:Workspace.open) and resolution happens against that root, reading no environment variable at all. Passing None -- or omitting the argument -- keeps the default behavior described above.

More tools from this site

  • claudestream Drive Claude Code from Python: run it as a subprocess and read its output as typed events, with async and sync sessions, sandbox policies, and tools you define in Python
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • fastware A batteries-included ASGI framework: msgspec JSON, a managed Granian server, dependency injection, SSE, WebSockets, auth, and a test client
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • howmuchleft The fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • safegit git wrapper CLI that gives each commit its own temporary index and retries ref updates on conflict, so concurrent agents share one repository
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • selfdoc Static Site Generator that builds a project's documentation site directly from its source code, so the docs can never drift from the code they describe, with SEO/AEO, first-class blog, search, and cross-project linking built in
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search