Set up Claude Code CLI

Use this path when you work in a terminal. Setup has three separate checks: load your role plugin, connect its Runtime tools, and supply the correct repositories and prepared Work Package. A connected server does not prove that Jira access or a handoff is ready.

1. Choose your distribution

For the current Runtime/Jira workflow, obtain praxis-runtime.mcpb and one matching role Skills ZIP from the configured release links. Check release-meta.json, version, checksum and compatibility before extracting. If a link leads to access information, request the release from the team. There is no public npm package or public marketplace assumed by this guide.

The following macOS/Linux terminal recipe uses Claude Code, Node.js 20 or later, and unzip. Windows users can extract the same archives and use equivalent absolute paths in their shell. Claude Code must be installed and authenticated for interactive Skills. Check the official Claude Code installation guidance.

# Shell — any directory. Check existing components before changing them.
claude --version
node --version
claude plugin list
claude mcp list

Reuse a compatible installation. Do not overwrite an existing praxis-runtime registration without checking its command, version and scope with claude mcp get praxis-runtime.

2. Extract and validate your role

This Developer example uses downloaded release assets in your Downloads folder. Set praxis_release_dir to their actual location. Use a new versioned directory when updating; keep the complete Runtime bundle, including its Quality companion and WASM file.

# Shell — any directory; these are local files, not package registry names.
praxis_release_dir="$HOME/Downloads"
praxis_install_dir="$HOME/.local/share/praxis/<release-version>"
mkdir -p "$praxis_install_dir/runtime" "$praxis_install_dir/developer"
unzip "$praxis_release_dir/praxis-runtime.mcpb" -d "$praxis_install_dir/runtime"
unzip "$praxis_release_dir/praxis-developer.zip" -d "$praxis_install_dir/developer"
claude plugin validate "$praxis_install_dir/developer"

The manifest must be at developer/.claude-plugin/plugin.json, with name praxis-developer. BA, Architect and Quality use their own authorized role ZIPs and manifest names. Do not install the whole role set for one teammate. The current ZIP supplies Skills; it does not contain the broader source tools or another MCP server.

--plugin-dir below loads the extracted plugin for that session. It is a local loading/testing mechanism, not a persistent marketplace installation. If your team supplies a marketplace, verify its actual manifest and accessibility first. Follow official marketplace instructions with the supplied source, plugin ID and intended scope; do not derive a public URL from a repository name.

3. Connect Runtime to the selected repository

Run this from the repository for the chosen role: BA/Architect use their shared product documentation checkout; Developer uses the code checkout with explicitly prepared local Runtime inputs. Replace the example path before running it.

# Shell — change to your chosen working repository first.
cd /path/to/code-checkout
claude mcp add --scope local --transport stdio praxis-runtime \
  -e PRAXIS_SKIP_DOTENV=1 -- \
  node "$praxis_install_dir/runtime/server/praxis-mcp.cjs" --role runtime
claude mcp get praxis-runtime
claude mcp list

local scope applies this registration to you in this checkout; it does not publish a project-wide .mcp.json or require teammates to install every role. Keep unrelated registrations. If Node is unavailable to the subprocess, register its actual absolute executable path instead of node.

Expect Connected. Registration alone is insufficient. A missing executable, wrong extraction directory, or incompatible Node version is a bootstrap problem; a role Skill cannot call praxis_doctor until Runtime is connected. The launch contract comes from the MCPB's manifest.json: server/praxis-mcp.cjs --role runtime. Importing the MCPB into Desktop does not register it in Claude Code.

4. Supply integrations without recording secrets

The Runtime/Jira Skills need Jira base URL, email, project key and API token. Desktop secure settings do not automatically populate a terminal. CLI Runtime reads PRAXIS_JIRA_BASE_URL, PRAXIS_JIRA_EMAIL, PRAXIS_JIRA_PROJECT_KEY and PRAXIS_JIRA_TOKEN from its environment. Keep PRAXIS_SKIP_DOTENV=1 to avoid reading a repository .env file.

Use your approved secret manager to inject the token into the launching shell. If using an interactive Bash terminal, this hidden-input alternative does not put the value in shell history or a configuration file:

# Bash shell — same terminal used to launch Claude. Never enable shell tracing.
export PRAXIS_JIRA_BASE_URL='https://example.atlassian.net'
export PRAXIS_JIRA_EMAIL='your-account@example.com'
export PRAXIS_JIRA_PROJECT_KEY='PRX'
read -r -s -p 'Jira API token (hidden): ' PRAXIS_JIRA_TOKEN
printf '\n'
export PRAXIS_JIRA_TOKEN

Replace the three non-secret examples with your actual Jira settings. Do not paste tokens into chat, claude mcp add -e, command arguments, screenshots, or committed files. Child Runtime processes inherit the launching shell's environment. Start a new Claude session after setting credentials. Git provider credentials are optional until you explicitly configure delivery; setup must not commit, push or create Jira work.

5. Load the role and check its tools

# Shell — selected working repository, same shell and variables as above.
claude --plugin-dir "$praxis_install_dir/developer"

Inside Claude, use /help to inspect role Skills and /mcp to check the server. These are interactive commands, not shell commands. For Developer, confirm praxis-developer:developer-status is available. Open a new session after changing the extracted plugin or use the reload action supported by your Claude version.

Start with this read-only request, replacing the path and the selected package identity:

Run praxis_doctor with repo=/path/to/code-checkout. Report version,
repository and configuration-presence flags without printing credentials.
Then run praxis_developer_status with the same repo and
workPackage=WP-001. Report missing handoff, evidence, manifest and claim.
A status response alone does not establish that this package is ready.
Do not initialize the project, claim work, write Jira, implement or deliver.

If .project is missing, inspect praxis_project_init_preview and obtain approval before praxis_project_init_apply. For a prepared package, follow Developer setup and handoff inspection. Runtime uses one repo for local input lookup and code/test execution. It does not import a sibling product checkout automatically. In the current Runtime path, completion evidence is under design/<Runtime-WP-id>/dev/; the separate source-tool path writes under the selected design directory.

Local source workflow without Jira

This is a separate distribution and workflow, not a fallback hidden inside the Skills ZIP. Obtain authorized Developer source with its checked-in vendor/*.tgz, package-lock.json and plugins/developer/tools/. With Node.js 20+ and npm, run npm ci from that source checkout, then load claude --plugin-dir /path/to/praxis-developer/plugins/developer from the code checkout. A missing vendor archive or source tool is a setup blocker; do not substitute an npm registry package. Read the two-root source recipe before using it: --design-dir points to the prepared shared product package, --product points to code, and reports use that design directory. Keep the BA requirements outside the Developer's write scope.

Verification boundary and recovery

Inspected release artifacts were checked with Claude Code 2.1.281 and Node 22.16.0 on macOS in an isolated CLAUDE_CONFIG_DIR. Developer manifest validation passed; local MCP registration reported Connected. Direct MCP initialization listed 45 tools, praxis_doctor reported missing Jira configuration without networking, and praxis_developer_status returned absent evidence for a disposable package. No Jira or Git publication occurred.

The isolated Claude profile had no login. An authenticated model session, live Jira access, Windows/Linux execution and an end-to-end fresh-machine install were not verified. Complete those checks in your authorized environment; do not treat the transport check as finished onboarding.

To remove only this CLI registration, run claude mcp remove --scope local praxis-runtime from the same checkout. Stop passing --plugin-dir to unload the session plugin. Keep repository artifacts unless you intend to delete them. Unset PRAXIS_JIRA_TOKEN when finished with the terminal.

See official local plugin loading and MCP scope and connection guidance.