Axon Shaft docs

Accounts and projects

The home page, accounts, projects and who can change them, the setup walkthrough, project status, and the permissions the app's installation still has to approve.

The dashboard is at shaft.axonpack.dev/console. You sign in with GitHub, and signing in brings you back to the page you opened.

Home page

/console is the home page, and Home in the sidebar comes back to it. It starts with Get started, the steps to your first review:

  1. Install the app on an account.
  2. Add a project.
  3. Add your Claude token.
  4. Add the workflow.

A step ticks itself once your accounts have it done, and each open step links to the page that finishes it. Get started shows until a project's first run reports back. Its × hides it in this browser.

Under it, Your accounts has a card for each account, with its plan, how many projects it has, how many of them need setup, and, for the account's admin, Permissions to review. The card opens the account. An account with no projects has Add project for the people who may add one. The last card, Add an account or organization, opens GitHub's page for installing the app.

On the home page a project needs setup until its first run, since the page doesn't read each repo's workflow file from GitHub.

Accounts

An account is a GitHub user or organization with the AxonShaft app installed. The account switcher at the top of the sidebar lists your personal account and your organizations, each with its plan, and ends with Add an account or organization. An installation shows up once it can reach at least one repo.

The account's page lists its projects, with a filter by status, a search (/ jumps to it), and grid or list views. Beside them:

  • Usage over the last 30 days: runs and tokens, and for the account's admin the approximate cost of runs on an API key and this month's spend against the monthly cap.
  • Alerts, which lists the permissions to review for the account's admin.
  • Recent runs: the newest 5.

While a run is going, the page reads again every 10 seconds, for up to 2 hours from the run's start (the longest time limit). A run still open after that never reported back, and the page stops waiting for it.

Who can do what

Axon Shaft uses the roles you already have on GitHub:

WhoWhat they can do
A member of the organizationSee the projects of the repos GitHub shows them, and their runs: the Overview and Runs pages.
Someone with the Admin or Maintain role on a repoAdd and remove that repo's project, and change its automations, settings and Claude token.
The account's admin (an org owner, or you on your personal account)All of the above on every project, plus the account's Claude token, settings, spending cap and audit log.

Write access to a repo isn't enough to change its project. Only the account's admin sets a monthly spending cap, the turn limit and the time limit.

To tell an organization's admins, the dashboard asks GitHub for your membership, which needs the app's Members permission. Without it, your role shows as Role unknown, and you can't change the account's settings. Manage account, in the profile menu, shows your role in each organization.

Projects

A project is one repo that Axon Shaft works on. Add project lists the repos you can add. Removing a project deletes its automations, its own Claude token and its settings. Its runs go with it.

A new project gets three automations, all on: Code review, Reply (for /ask) and Task (for /fix and /axonshaft). See Automations.

Setup

The setup walkthrough opens right after Add project, and from the Set up button on the project's Overview:

  1. Add the workflow. "Add workflow directly" commits .github/workflows/shaft.yml to the default branch, and "Add workflow via PR" opens a pull request, which is the only choice when the branch is protected.
  2. Claude token. Optional: skipping it uses the account's token.
  3. Model and effort. A project always has them, Auto by default, so this step counts as done.
  4. Automations, with a switch each.
  5. First run, with a link to open a pull request.

A project is set up once an automation is on, it or its account has a Claude token, and the workflow file is on the default branch. It doesn't have to have run. Closing the walkthrough keeps your progress. Members never see it.

Status

StatusWhen
ReadySetup is done.
Needs setupAn automation, a Claude token or the workflow file is still missing.
FailingThe last run failed or timed out.
PausedSomeone paused Axon Shaft on the repo.

The project's pages

  • Overview: the project card with its status and last run, runs, verdicts and failures over 7 days, the automations, and the newest run on each pull request from the last 7 days.
  • Runs, Automations, Settings and Claude token. Members see only Overview and Runs.

The Overview reads again the same way as the account's page while a run is going.

The Overview also shows, to whoever may change the project:

  • a Workflow needs an update card when the workflow file differs from the one the dashboard gives, listing what's missing or different, with a button that opens a pull request with the new file;
  • a New action version card when the workflow pins an older release. See Pinning the action.

Axon Shaft finds its workflow under any file name in .github/workflows/ on the default branch.

Settings

The project's Settings tab has the same sections as the account's, without the Claude token, Max turns, Time limit and Audit log. A field the project doesn't set shows the account's value or the default, locked until you choose Override. Review rules add up, the account's first. A project's own merge gates replace the account's. Every setting is on the Settings reference.

The Danger zone pauses Axon Shaft on the repo, or removes the project.

Permissions to review

When the AxonShaft app asks for a new permission, each installation keeps its old set until someone approves the new one on GitHub. Until then, the features that need it don't work. The dashboard shows the account's admin what's waiting:

  • in Alerts on the account's page, with each permission, the access the app asks for and what doesn't work without it;
  • on the project's Overview, as the same card;
  • in a bar over every project page, which you can dismiss for the browser session;
  • in the notifications bell.

"Review on GitHub" opens the installation's settings. GitHub App permissions lists what each permission is for.

PermissionWithout it
Contents, Pull requests, IssuesReviews can't post.
ChecksReviews don't post their check runs.
WorkflowsThe dashboard can't add or update the workflow file.
Code qualityThe Code quality checklist can't read GitHub Code Quality's findings.
Repository security advisoriesBlocking security findings can't go into private draft advisories.

Members and repo maintainers don't see any of this, since only the account's owner can approve permissions.

Last updated on