Praxis keeps your team’s tickets and AI agents in the same project. Start with an organization, add a project, then invite people or connect your coding tool.
Accept your invitation. Create an account, or sign in with the invited email. An organization invitation lets you create a workspace; a teammate invitation joins an existing one.
Create your first project. Choose a name and ticket prefix, or import a Praxis archive or Jira CSV export.
Connect your AI tool. Open AI tools to create a personal project key and copy its setup prompt.
Start with a ticket. Describe the task, assign it if needed, and move it through your team’s statuses.
You can start using the board before connecting GitHub or an AI tool. Public self-signup is not enabled for an existing installation; ask an admin for an invitation.
An organization contains its people, projects, and settings. A project contains a board of tickets. Switch organizations from Workspaces and use the project selector on the board when you have multiple active projects.
Open the organization name in the board header, or use Workspace in the mobile menu. From there, use Projects, People, AI tools, or Settings. Available controls depend on your access.
A board/component within a project is a way to group tickets, such as frontend and backend. It does not create a separate organization or project.
Your organization’s display name can change. Its workspace address stays stable so existing links continue to work.
Create, archive, import and export
Create a project
In Projects, choose Create project. Give it a name and a short letter prefix such as WEB. Tickets receive keys like WEB-1. Choose the prefix carefully: it cannot be changed later.
Archive a project
Open the project’s Settings and choose Archive project. Its tickets and history remain stored, and the project moves to the Archived tab. Restore it from the same settings when you want to resume work.
Move a project between workspaces
Choose Export on the project card to download its Praxis archive.
In the destination organization, choose Import project and upload the archive.
Review the preview, choose the new name and prefix, then confirm the import.
Imports create a new project; they do not overwrite the source. Content and attachments are included, but credentials and active agent claims are not. Review people and integrations after importing. Choose Import from Praxis for a Praxis ZIP archive. Choose Import from Jira for a CSV export of one Jira project, with Key or Issue key, Summary, Issue Type, and Status columns. Jira ticket numbers and epic relationships are preserved. Review the preview warnings and map assignees before importing. Extra exported fields remain in ticket descriptions; attachment files and Jira history are not imported. Both options are also available in the setup wizard.
Team and agent instructions
Project Settings includes optional instructions for board conventions, repository layout, or how the team should work. Agents read these alongside the generic workflow.
Use New to create a ticket. Write a specific title and description, then choose its type, priority, assignee, and optional parent epic. Open a card to read details, discuss the work in comments, and add attachments.
Backlog / To Do
Work to plan or pick up.
In Progress
Work currently underway.
Blocked
Work waiting on a dependency or another decision.
Under Review / Done
Work awaiting review, or completed.
On desktop, drag cards between columns or change status inside a ticket. On mobile, tap a status tab to see its column and use Move on a card. Status tabs stay below the header while you scroll.
Find the right work
Search by ticket key, title, description, or comments. Filters narrow results by component/board, epic, type, priority, assignee, and recent activity. Mine shows work assigned to you. Sort the board within each status by priority, story points, epic, update time, or title. Unestimated tickets appear last in either story-points direction. Default order restores drag reordering. If expected tickets disappear, clear filters before assuming they were deleted.
The colored availability bar
The bar groups open work by whether it is ready to pick up, active, claimed but not started, or blocked. These groups can cross status columns. Tap a segment to filter that group; choose Showing all work to clear the availability filter. On mobile, Details expands the legend.
Dependencies and agent claims
Dependencies explain what must finish before another ticket can proceed. An agent claim records who has picked up work; it is different from the assignee and from ticket status. Read the ticket’s details before taking over someone else’s work.
Board, Tree, Deps, Map and Flow
Board
Manage work by status. Desktop columns scroll independently; mobile shows one selected column at a time.
Tree
Explore epics and their child tickets. Use the expand control on the right to open or collapse children.
Deps
Explore dependency chains and the work blocking other tickets.
Map
Explore tickets spatially. Pan, zoom, and use the view’s controls to find related work.
Flow
Review how work moves through statuses and how long it takes. Historical activity is needed for useful metrics.
Use the view buttons at the top on desktop or the bottom on mobile. Refresh reloads current app data without resetting your selected workspace and filters.
Desktop shortcuts
Key
Action
c
New ticket
/
Focus search
Ctrl/Cmd + F
Find a ticket
b / t / d / m / w
Board / Tree / Deps / Map / Flow
n
Notifications
?
Show keyboard help
Connect an AI coding agent
Sign in with your own organization account and open AI tools → Connect an AI tool.
Choose one or more active projects, name the key, and select your AI tool or Detect my tool.
Choose 30 days, 90 days, 1 year, or Never expires. Create the key and prompt.
Copy the setup prompt into your AI coding tool with the intended repository open.
Let the tool validate the key, configure its MCP connection, read the project workflow, and report the connected organization and project. Follow any manual steps or restart instructions it reports.
The prompt adapts setup to the tool and operating system. Tools with remote MCP support can connect directly; others may need a bridge or manual configuration. Copying the prompt does not by itself prove that the connection succeeded.
Connection details
MCP server:
Metadata check:
Generic workflow:
Authenticate those requests with Authorization: Bearer <YOUR_KEY>. The generated prompt includes your actual key and project.
Keys and expiry
The personal key appears once. Store it in private tool settings or an untracked local environment file. If you lose it, choose Regenerate key. Confirm the replacement, then update every tool that used the old secret. Your project access and permissions stay the same.
In AI tools, choose Edit key to rename it, select projects, change permissions or adjust expiry. Your existing key stays the same. Setup prompt lets you reuse the credential saved in your AI tool. For a new device, paste your saved key into the optional field; it stays in your browser and is not stored by Praxis. Choose which project the repository belongs to before copying.
Never expires removes the time limit, not the access checks. Revoking the key, losing membership or project access, or suspending the organization can still stop the connection. Each teammate should use their own key. Agent keys do not grant Super admin access.
The connections list shows expiration and last-use information. Revoke a key when its tool no longer needs access.
Use these steps when you prefer to configure the connection yourself, or when the automatic prompt does not finish setup. You need a personal Praxis key and an AI tool that supports remote MCP with bearer authentication.
1. Choose your project and key
Open AI tools in your organization. Create a key with access to the project, or use one you saved earlier. If you lost it, choose Regenerate key, confirm the replacement, and copy the new prompt. Only the key owner can regenerate it. Every tool using the old secret must be updated.
Keep the new key in your tool’s private credential settings. Do not put it in a repository, a shared chat, or a URL. A key with several allowed projects still needs one project selected for this repository.
2. Add a remote MCP connection
Open your AI tool’s MCP or external-tools settings and add a server. Exact menu names and configuration files vary by tool. Enter these values:
Name
Praxis
Transport
Streamable HTTP, sometimes labelled HTTP or remote MCP
Server URL
Authentication
If there is a Bearer token field, paste only the key. If the tool instead accepts custom HTTP headers, set Authorization to Bearer YOUR_KEY, with a space before the key.
Use the public Praxis address when the agent runs on another machine. 127.0.0.1 refers to the machine running that agent. Praxis personal keys use bearer authentication; choose the token/header option rather than an OAuth sign-in flow.
Save, then enable the server and reload its tools. Restart the client if its documentation requires it. Merge the server entry into existing configuration so other MCP connections remain available.
My tool only supports local MCP servers
It needs a local HTTP bridge that supports Streamable HTTP and forwarding the Authorization header. Follow your client’s official bridge instructions. A local command field cannot use the server URL as an executable. If the client supports neither a remote connection nor a compatible bridge, it cannot use this MCP endpoint directly.
3. Check the key separately from the client
These commands ask for the key without including it in shell history. They read your account metadata and download the workflow instructions. They do not create tickets. Run them in a terminal on the same machine as your agent. The downloaded file contains instructions, not your key.
Check that the metadata names the expected organization and includes your project. If it does not, change the key’s project access or ask your organization admin. A successful metadata request verifies the key and server; it does not yet prove that your AI tool is configured correctly.
4. Add the project workflow
Read praxis-workflow.md, then add or reference its instructions in the project-instructions mechanism supported by your AI tool. Preserve existing repository instructions. You can also retrieve the workflow from with the same Authorization header.
Record the intended organization and project key in the repository’s non-secret setup instructions. Tell the tool to use that project explicitly when calling Praxis. Keep the credential separately in private client settings.
5. Verify the AI tool connection
Reload the client’s MCP tools and look for praxis_meta. Run it with your project key, then use the discovered read-only search or board tools to list existing work. Some clients prefix tool names with the server name. Confirm the organization, project and permissions before asking the agent to change tickets. No test ticket is necessary.
If a step fails
401 or an invalid key: check for extra spaces, expiry, revocation, or a recently regenerated secret. Update all clients with the current key.
403 or a missing project: check the key’s permissions and selected projects, your membership, and whether the organization is active. Regeneration does not grant additional access.
Connection refused or timeout: check the address and network from the agent’s machine. A local development address cannot reach a server on another computer.
Metadata works but tools are missing: recheck Streamable HTTP, the Authorization header, and your client’s reload requirements. A plain browser visit to /mcp is not an MCP handshake.
Organization admins use People to invite teammates, change roles, and remove or restore membership. Select any starting projects in the invitation. For an existing teammate, use their Projects button to add or remove access; organization admins already have all projects. Share the generated invitation link with the intended person; creating a link does not send an email automatically.
Viewer
Read permitted project work.
Member
Work on permitted tickets and connect personal AI tools.
Admin
Manage their organization’s projects, people, and settings.
Super admin
Manage organizations across the platform, including invitations, capacity, suspension, and account recovery.
For accounts with both roles, the mode selector changes the administration view. Admin mode shows organization controls. Super admin mode shows Organizations, customer invitations, and account recovery. The selector does not revoke either role.
Restore reactivates organization membership. If the account is disabled across Praxis, a super admin can restore it from People. The person must sign in again, and old agent keys remain revoked.
To onboard a customer, select Super admin, choose Invite organization, and share their invitation link. They create their account and organization and become its admin. A teammate invitation joins the existing organization instead.
Removing a teammate blocks their access to that organization and their agent keys there. Their historical work and memberships in other organizations remain. Restoring membership does not restore already revoked keys.
Open a project’s Settings and expand GitHub integration. Register repositories as owner/repository, configure the GitHub webhook secret, and use the webhook URL shown for that project.
The webhook secret verifies incoming events. The GitHub API token is a separate credential used to read GitHub data. Configure automatic ticket updates with organization defaults or project-specific rules.
What does Backfill lines changed do?
It fills missing additions, deletions, and changed-file counts for pull requests already linked to this project. Each click considers up to 200 PR records, using the saved GitHub API token and registered repository list.
It updates statistics in Praxis without changing repository code, PRs, or ticket status. Save token and repository changes first. The result reports updated, remaining, and skipped records. If GitHub rate-limits requests, wait before trying again. Remaining records may require repository access or configuration fixes.
An optional notification webhook sends project activity to a configured destination. Leave integration fields unchanged if you do not need them.
Device notifications
Praxis can notify this device about mentions and ticket assignments even when the app is not open. Your in-app inbox works whether or not you enable device notifications.
Choose Enable notifications and allow the browser permission request.
Choose Send test notification to check delivery. Enable each browser or installed app separately.
iPhone and iPad
On iOS or iPadOS 16.4 or later, use Share → Add to Home Screen. Open Praxis from that icon, sign in, and enable notifications there. A regular browser tab on these devices cannot receive Praxis push notifications.
Mac
Safari supports Web Push on macOS Ventura 13 or later. Current Chrome, Edge, and Firefox versions also support Web Push on Mac. Enable notifications separately in each browser or installed app.
Windows and Android
Use a browser that supports Web Push over HTTPS. Installing the PWA is optional on supported desktop and Android browsers. The page can be closed; delivery still depends on the browser’s background permissions and your operating system.
Privacy and control
Notifications show that a ticket needs attention without revealing its title or description on the lock screen. Tapping opens the ticket; normal sign-in and project permissions still apply. Signing out disables this device. Password changes, account deactivation, and lost project access also stop delivery. Only new inbox activity after enabling is sent.
Use Disable on this device to stop push without changing your other devices or inbox. Devices that have not checked in for 30 days need to be enabled again.
Test delivery failed?
If the push service is temporarily unreachable, keep notifications enabled and retry in a minute. If the subscription expired, use the Enable notifications button to renew it. A server authorization error needs an administrator to check the push configuration.
Nothing arrived?
Check browser/site notification permission, OS notifications, Focus or Do Not Disturb, battery restrictions, and network access. If permission was blocked, change it in browser or device settings and reload. A successful test submission means the push service accepted it; it does not prove your OS displayed it. No notification system can override a force-quit browser or device restrictions.
Administrators should serve Praxis over HTTPS, keep its database volume persistent, and allow outbound HTTPS to browser push services. The WebKit guide explains Home Screen support on Apple devices.
Account and troubleshooting
Your appearance
Open Personal settings → Appearance, or Theme on the board. Every user, including viewers, can choose a personal theme. Choose Ink or one of ten other palettes, Light, Dark, or System mode, and optional custom primary, secondary, and neutral colors. Light and dark keep separate custom colors. Save appearance applies your choices across your workspaces and devices; other users keep their own themes. Cancel changes restores your saved theme; Restore default previews Ink with System mode.
Your account
Open Personal settings and choose Account to see your name and email and change your password. A password change signs out your other sessions. Sign out asks for confirmation; Stay signed in or Escape cancels it.
App updates
When an update is available, Praxis shows a prompt with Reload app and Later. Save any open work before reloading. Later leaves your current page open; the latest version loads on your next navigation or reload.
I cannot sign in or accept an invitation
Use the invited email address. Ask your admin for a fresh link if the invitation expired or was revoked. For a forgotten password, use the sign-in page’s recovery help and contact your admin; a Super admin can create a recovery link.
My agent cannot connect
Check the server address, key, expiration, organization, and project. Make sure your membership and organization are active. The project must be selected on the key and accessible to its owner. For a multi-project key, choose a project in the setup prompt. Follow your AI tool’s manual configuration or restart instructions when needed.
I cannot find a project or ticket
Check the selected organization and project, clear filters, and look in the Archived tab. Ask an admin to check your project access if it is still missing.
A control is missing
Controls depend on your organization role and selected administration mode. Viewers do not have AI tools or editing controls. A Super admin must also be a member of an organization to create a personal agent key there.