Skip to content

[Feature] Add discoverable PawWork home for global user config #328

@Astro-Han

Description

@Astro-Han

What task are you trying to do?

Users need a predictable, easy-to-find place for PawWork-wide personal configuration.

The concrete task is: create or edit global instructions/configuration that should apply across all PawWork sessions, especially files such as:

  • global AGENTS.md
  • global pawwork.json
  • user-level skills / commands
  • user-level MCP-related configuration

These are human-editable files, not runtime-managed app data.

What do you do today?

Today PawWork's global AGENTS.md is loaded from the app runtime config tree. On macOS, that currently resolves to a path like:

~/Library/Application Support/ai.pawwork.desktop/config/pawwork/AGENTS.md

That follows Electron/platform app-data conventions, but it is painful for this workflow because users have to either:

  • know a deep platform-specific runtime path,
  • ask PawWork where the global AGENTS.md is loaded from,
  • set PAWWORK_CONFIG_DIR manually,
  • or keep project-level AGENTS.md files even when the rule is really global.

It also mixes two different categories of files:

  • human-edited, syncable config;
  • runtime-managed app data/cache/state/logs.

That makes the config harder to discover, harder to document, and awkward to manage with dotfiles.

What would a good result look like?

PawWork should have a clear global user configuration home for files that humans are expected to edit and possibly sync across machines.

A good result would let users reason about global config with a simple model, for example:

~/.pawwork/
  AGENTS.md
  pawwork.json
  skills/
  commands/
  mcp/

Runtime-managed files should remain in platform app data/cache/state locations, for example:

  • session databases
  • logs
  • caches
  • tool output
  • snapshots / undo state
  • Chromium/session data

Possible acceptance criteria:

  • Add an explicit global config home concept, e.g. PAWWORK_HOME.
  • Default the human-editable config home to a discoverable path such as ~/.pawwork.
  • Continue supporting the existing platform config path for backward compatibility.
  • Define clear precedence for global AGENTS.md and pawwork.json.
  • Avoid moving cache/log/database/session data into the human-editable config home.
  • Provide an app command or UI entry like “Open global config folder”.
  • Document the distinction between global user config, project config, runtime data, and enterprise/managed config.

One possible precedence model for global instructions:

1. PAWWORK_HOME/AGENTS.md
2. ~/.pawwork/AGENTS.md
3. existing platform config AGENTS.md
4. project AGENTS.md / CLAUDE.md / CONTEXT.md

Which audience does this matter to most?

Both

Extra context

PawWork is cross-platform, not macOS-only. The current platform app-data layout is useful for runtime data, but less discoverable for developer/agent-style global config.

Relevant prior art:

  • Claude Code uses user scope at ~/.claude/, including ~/.claude/CLAUDE.md, ~/.claude/settings.json, and ~/.claude/agents/.
  • Codex uses ~/.codex/config.toml for user-level config and .codex/config.toml for project overrides.
  • GitHub CLI exposes GH_CONFIG_DIR and defaults to XDG/platform config locations.
  • VS Code stores user settings in platform locations, but exposes commands to open the settings JSON directly.
  • Electron's userData path is suitable for app configuration/runtime data, but Electron also warns not to put large files there because some environments back it up.

The key product distinction should be:

  • Human-editable global config: easy to find, document, and sync.
  • Runtime-managed app data: platform-appropriate app data/cache/state locations.
  • Secrets/tokens: credential store/keychain where possible; not in AGENTS.md.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Medium priorityappApplication behavior and product flowsdesktopElectron shell and desktop packagingenhancementNew feature or requestharnessModel harness, prompts, tool descriptions, and session mechanics

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions