Persistent agent, or pa, is a claude-based agent memory, and task system that allows a user to delegate work to an agent, and for the agent to act on behalf of the user.
pa's current state is stored as markdown files and is meant to be easily interpretable and customized.
Read the blog post for motivation and background.
You'll need to have to have Claude Code installed. Then fork this repo, likely into a private repository. Now it’s your own thing to use and change, for personal use, work use, or both.
Clone your fork locally and cd into it.
Run bin/pa install to add pa to your global $PATH.
You can call pa it from any folder, but it will always run in this folder.
If you want to run multiple pa, or if you don't want a global install, you can use the local bin/pa instead of globally installed pa.
Then run pa setup <your name> to perform first-time user setup.
It will ask you for the tools and repositories you want on your workspace, and you can answer in github shorthand like metabase/metabase or your-org/your-repo.
It will also tell you how to connect tools it needs to work.
You use pa by alternating between modes: pairing with the agent, and leaving the agent to work autonomously.
Run pa then say sod or pair to trigger the start-of-day routine.
pa will look at tasks and updates from tools to propose a day plan and a slack start-of-day draft.
It will then try to unblock itself and others that are waiting for your input.
Give pa tasks to work by telling it to add them to its todos.
Then say work and pa starts working on them autonomously on a repeating work loop, checking for newly-assigned work every 30 minutes.
You can also start pa on the work loop from the CLI with pa work.
Say pair to get the current status from pa, unblock or work with it. Then say work again to continue autonomously.
pa <anything> will just start pa with <anything> as prompt, with a few exceptions that are plain scripts instead:
pa install: installspainto$PATHpa save: git commit changes to tasks and daily notespa today: show todays daily notepa tasks: lists task statuspa backlog <text>: adds a new task to the backlog folderpa todo <text>: adds a new task to the todo folderpa update: pull new changes topaand merge them into the current branch
pa starts in auto mode, which uses Claude itself to allow or deny permission prompts.
You can edit (or ask pa to) .claude/settings.json with ask/deny rules for things that you want to manually control permissions for.
Use shift+tab to switch modes if you want stricter or looser behavior.
Run pa update to fetch and merge the latest changes from upstream. Conflicts are resolved automatically using CHANGELOG.md for context.
You can and should edit pa to suit the way you work. The memory folder has all the instructions on how pa works as markdown files.
Edit them directly or work with pa on self-modification tasks.
If you want to contribute them back to a shared pa repo, ask pa to help you do that or follow the instructions in memory/skills/self-modification.md yourself.
Use Claude's remote control to drive a local pa session from the Code tab in the Claude mobile app.
To enable it type /remote-control inside an existing session, or run /config and set Enable Remote Control for all sessions to true.