Feature request: configurable agent instructions / working directory (git support)

[damiencal]

Summary

Currently, agent instruction files (AGENTS.md, HEARTBEAT.md, SOUL.md, TOOLS.md, etc.) live inside Paperclip's app-data directory:

~/Library/Application Support/Paperclip/instances/default/companies/<companyId>/agents/<agentId>/instructions/

This makes it impractical to manage those files in git, which the Paperclip Company Playbook explicitly recommends (separate repo, version-controlled agents/, anti-pattern tables that grow over time, git diff after Founder corrections, etc.).

I'd like to propose a way for users to point Paperclip Desktop at an external, user-managed directory for an agent's instructions, so the playbook's git-based workflow works out of the box.

Why this matters

The playbook is built around the idea that agent files are living documents that improve over time:

• HEARTBEAT anti-pattern tables grow as the Founder catches mistakes
• AGENTS.md responsibilities get refined per role
• SOUL.md identity rules are tuned as drift patterns are discovered
• New skills (e.g. third-party tool integrations) get appended to TOOLS.md

Without git, all of that history is lost — and rolling back a bad CEO instruction edit becomes a manual restore from backup.

There's also a privacy/safety dimension: prospect lists, founder emails, and strategy notes belong in a private GitHub repo, not buried in ~/Library/Application Support/.

Current workaround (and why it's not great)

Today you can symlink the instructions directory:

PAPERCLIP_CEO_DIR="$HOME/Library/Application Support/Paperclip/instances/default/companies/<uuid>/agents/<uuid>/instructions"
mv "$PAPERCLIP_CEO_DIR" "${PAPERCLIP_CEO_DIR}.bak"
ln -s ~/code/my-company/agents/ceo "$PAPERCLIP_CEO_DIR"

Problems with this:

• Requires the user to dig up two UUIDs from a deep app-support path
• App updates may rewrite or replace the instructions dir, breaking the symlink silently
• Not discoverable — nothing in the UI hints that this is possible
• Doesn't survive a Paperclip reinstall or a default instance reset
• New users following the playbook will all hit this same friction independently

Proposed solutions (in order of preference)

1. UI-level: "Working directory" / "Instructions path" field on agent

In the agent settings panel, add a field:

Instructions directory (optional)
If set, Paperclip will read agent instruction files from this path instead of the default app-data location. Useful for managing agents in version control.
[ ~/code/my-company/agents/ceo ___________________ ] [ Browse… ]

When set:

• Paperclip reads AGENTS.md, HEARTBEAT.md, SOUL.md, TOOLS.md, memory/, etc. from that path
• Writes (e.g. memory updates) go to the same path so the user's repo accumulates state naturally
• Empty / unset = current behaviour (use app-data dir)

This is the cleanest fix and matches how most dev tools handle workspace paths.

2. Per-company-level: a single root path for the whole company

Same idea but at the company level — set one root (e.g. ~/code/my-company/), and Paperclip looks for agents/ceo/, agents/sales/, etc. inside it. Matches the directory structure the playbook already prescribes.

3. Config-file-level: allow a JSON/YAML override

For users who'd rather not click through UI, a config like:

# ~/.paperclip/config.yml
companies:
  79a4970b-37bd-456d-9d5f-eed4c4e2b653:
    instructionsRoot: ~/code/posdo-company/agents

Less discoverable than option 1, but quick to ship and unblocks power users.

Acceptance criteria (rough)

• User can set an external instructions path for an agent or company
• Paperclip reads instruction files from that path on each heartbeat
• Writes (memory, daily notes, etc.) target the same path
• Path setting persists across app updates
• Documented in the README and ideally in the playbook
• Behaviour when path doesn't exist or is unreadable is graceful (clear error, not silent fail)

Related

• Paperclip Company Playbook: https://github.com/aronprins/paperclip-company-playbook
• Upstream Paperclip: https://github.com/paperclipai/paperclip — happy to cross-post there if this needs to land at the server level rather than the desktop wrapper.

Environment

• macOS (Apple Silicon)
• Paperclip Desktop v1.0.0
• Use case: following the Paperclip Company Playbook for a real SaaS company with multiple agents and version-controlled instructions