This page is for your AI assistant (Claude, Codex or Cursor). You give it one short prompt, and it walks you through the setup.
Copy this into your current or a new chat with your assistant:
Set up Keeptrack with me in this conversation: read https://github.com/rain-ventures-ai/keeptrack/blob/main/START.md and follow it one step at a time. Do not just explain the options—start by asking me the first setup question.
The web board has the same prompt with your board and username filled in: Settings → Agents & integrations → Claude or Codex in your chat app → Copy setup prompt.
Keeptrack keeps one board in the board/ folder of the person’s own private GitHub repo. board/tasks.json is
the board’s entry point and settings file; current boards keep individual tasks in board/cards/ and CRM people in
board/people/. Tasks and CRM are optional modes of the same board, not separate databases. People use the web board
at https://rain-ventures-ai.github.io/keeptrack/board/. Agents use keeptrack.py, which comes with the keeptrack
plugin.
When the person already has <OWNER>/<BOARD-REPO>, give them these instructions directly:
<OWNER>/<BOARD-REPO>. Show my tasks and anything needing attention.” Nothing needs to
be installed: cloud sessions do not load plugins, and the board repo already has CLAUDE.md, the board skill and
board/keeptrack.py. The Claude GitHub connection supplies repo access; do not ask for a PAT.gh auth status, cd into the
repo and start claude. Use the same prompt. Do not install the plugin and do not ask for a PAT when gh is logged
in and can access the repo.<OWNER>/<BOARD-REPO> for that project. The plugin is for this cross-project case.Then verify read access with where and list or today. Ask permission before adding a small test task, verify it
appears on the web board, then finish or delete it. Do not merely explain the cases and stop.
Claude’s current documentation confirms that cloud sessions can include multiple repositories and do not load plugins declared by a repository: https://code.claude.com/docs/en/desktop#install-plugins
A PAT is required by the web board in the browser. A local agent needs one only when there is no usable gh login.
Claude Code cloud working from the board repo does not need one. Never lead a cloud or already-authenticated local user
through token creation.
When a token is needed and you know the board’s owner/repo, give the person a clickable link with that owner and
the required permissions pre-filled. Do not send them only to the generic token list. Replace <OWNER> and <REPO>
in this template and URL-encode their values:
https://github.com/settings/personal-access-tokens/new?name=Keeptrack%20<REPO>&description=Keeptrack%3A%20read%20and%20write%20board%2Ftasks.json%20and%20create%20issues&target_name=<OWNER>&expires_in=90&contents=write&issues=write
Say this immediately below the link: “GitHub has pre-filled the resource owner and Contents/Issues: Read and write.
GitHub cannot preselect a private repo from a link, so under Repository access choose Only select repositories, then
select <OWNER>/<REPO>.” The person generates and copies the token; you never see it. If they already made a PAT,
offer the pre-filled new-token link as the simplest fix and also link to
https://github.com/settings/personal-access-tokens so they can edit the existing one themselves.
Ask the person two questions (one line each, with your recommendation):
rain-ventures-ai/consulting) and what is your GitHub username?If you are ordinary Claude chat (you cannot run commands or clone the repo), say so plainly and do not pretend to install anything. Take the person through the phone and claude.ai path below instead.
If they already have a board and asked about Claude Code cloud or local use, take the fast path above and then go to step 4. Otherwise go to step 2.
Use this when the person is on a phone, or talks to you in claude.ai in a browser.
<OWNER>/<BOARD-REPO>.”First check whether the assistant is already running in the board repo (look for board/keeptrack.py). A board repo
contains its own instructions, skill and CLI, so it does not need the plugin. Claude Code cloud cannot load plugins;
start its session on the board repo, or add the board repo as a second repo.
Install the plugin only when the assistant is local and working from a different project, or when the tool needs the general Keeptrack integration.
Check before installing. The person may have installed it already. Look first, and skip the install when it is there:
keeptrack skill (for example keeptrack:keeptrack) in your list of skills? Locally, also run
claude plugin list (or codex plugin list) and look for keeptrack.Only when it is missing:
| Tool | What to do |
|---|---|
| Claude Code locally, from another project | Run claude plugin marketplace add rain-ventures-ai/keeptrack then claude plugin install keeptrack@keeptrack. Tell the person to start a new session so the skill loads. |
| Claude Code cloud (claude.ai/code, or the Code tab in the desktop or phone app) | Do not install a plugin. Select the board repo for the session, or add it as a second repo. |
| Ordinary Claude chat (claude.ai or the phone app, not Code) | Nothing to install: it cannot update the board. Use the phone and claude.ai path above. |
| Claude desktop app or Cowork | The person does this: open https://claude.ai/customize/plugins (or Customize → Plugins in the app), click Add → Add marketplace, type rain-ventures-ai/keeptrack, then install keeptrack. Then start a new chat and paste the prompt again. If it says “Failed to add marketplace”, first check whether it is already listed (it may have been added before); if not, try once more with https://github.com/rain-ventures-ai/keeptrack; if that also fails, use the Claude Code fast path above. |
| Codex | Run codex plugin marketplace add rain-ventures-ai/keeptrack, then the person types /plugins and installs keeptrack. |
| Cursor | The person types /add-plugin https://github.com/rain-ventures-ai/keeptrack in Agent chat. |
If this is the board repo or the plugin is already installed, say so and go on. Details: board/kit/PLUGIN.md.
Useful links for the person: Claude plugins https://claude.ai/customize/plugins · make a private repo https://github.com/new?name=my-keeptrack&visibility=private · edit an existing GitHub token https://github.com/settings/personal-access-tokens (for a new token, use the pre-filled template above) · the web board https://rain-ventures-ai.github.io/keeptrack/board/
Choose the command once. Below, $B means it:
python3 board/keeptrack.py.python3 <board-repo-folder>/board/keeptrack.py.keeptrack.py as the plugin skill says (in Claude Code it is under
${CLAUDE_PLUGIN_ROOT}).The web page makes the board. It is the easiest way, also for people who do not use a terminal.
my-keeptrack and Private already set), and make a token (it opens GitHub’s token page with the right permission already set; the person picks the new repo, generates the token and pastes it into the page, not into the chat).chris-smith/my-keeptrack) and their GitHub username, then go to step 3b.
If the person wants to try first, they can look at the demo: https://rain-ventures-ai.github.io/keeptrack/board/?demo=crmIf $B is the copy inside the board repo, it gets the repo and branch from that clone. Do not run use; just verify:
$B where
If $B is the plugin copy in another local project, connect that project once:
$B use <owner/repo> --user <github-username>
$B where
use writes .keeptrack/config.json (git ignores it, and it holds no token; the older .board/config.json still works). Add --project <name> in a code repo to make that board project its default. keeptrack.py looks for that file in the current folder and each folder above it, so run use inside each project that should use the board, not in the home folder: a person with more than one board would then send every project’s commands to one of them. A clone of a board repo always uses its own git remote; a config in a folder above it is ignored. where shows which board is in use.
AGENTS.md is not part of the data format and the web board does not need it. A board repo that agents work inside
should have it: keeptrack.py init creates AGENTS.md plus CLAUDE.md, and they tell repo-local agents to use the CLI
instead of editing board files. When the assistant uses the installed plugin from another project, the plugin skill
provides those operating rules instead.
The assistant also needs access to the repo. Pick the first that applies:
gh auth status. If it says logged in and can see the repo, nothing more
is needed. Otherwise ask the person to run gh auth login themselves.KEEPTRACK_TOKEN; you only learn the
variable’s name. Then run $B use <owner/repo> --user <github-username> --token-env KEEPTRACK_TOKEN when using
the plugin copy.$B where and $B today. If keeptrack.py cannot reach GitHub there, set
the person up with Claude Code cloud instead.For people who do not use a terminal, this is the main way. It works in a browser (https://claude.ai/code), in the desktop app and in the phone app (the Code tab), and it needs no GitHub token.
CLAUDE.md, the board skill and keeptrack.py. The cloud blocks GitHub
API writes, so keeptrack.py saves with git push from the clone by itself.python3 <board clone>/board/keeptrack.py. A plugin copy cannot save there, because it is not in a clone of the board repo.$B today # people to contact (if the board tracks people)
$B list # tasks (if the board tracks tasks)
Both must run with no error. Then ask the person to look at the web board, and add a test with their OK, for example $B add "Test from my assistant", and ask them to check that it shows on the web board. Delete or finish the test task after.
Then offer the guided import once: “Would you like me to bring in existing people and clients (CRM), tasks, or
both?” A yes hands over to onboard-keeptrack. If the skill is not available in this session, do not substitute
your own import process; start a fresh session on the board repo after the plugin/kit is current.
Give three examples, in their words:
If the person wants to type @claude in a task comment on the web board and have Claude do the task in the cloud, tell them to open the web board, then Settings → Agents & integrations → @claude in task comments, and switch Use @claude on. The page has five steps with a check for each. Full guide: board/kit/ROUTINE-SETUP.md.
board: (none): run step 3b.HTTP 404 or 401: the token or login cannot see the repo. Check the repo name, and that the token includes this repo.HTTP 403 when you save: the token has Contents: Read only. The person edits the token on GitHub and sets Contents: Read and write.