ProjectCtx documentation

Troubleshooting

Diagnose installation, connection, authentication, scanning, and memory issues.

Start with:

projectctx doctor

Doctor reports runtime, client configuration, and optional CLI credential and workspace checks without printing token values. It cannot inspect OAuth state owned by another client. Its output is safe to share after a quick review. Never share raw config files or login commands containing credentials.

Installation

If projectctx is not found:

npm install -g @projectctx/agent@alpha
npm prefix -g

Ensure the global npm binary directory is on PATH, then open a new terminal.

Connect Preview Shows No Clients

projectctx connect detects clients by their local config directories. Launch the client once so it creates its configuration, then rerun:

projectctx connect --dry-run
projectctx connect

ChatGPT, claude.ai, and Claude Desktop use account-side connector settings and are always printed as manual steps rather than detected local clients.

MCP Client Cannot See Hosted Memory Tools

Run projectctx connect --dry-run and confirm the client is detected.
Apply the configuration with projectctx connect.
Fully restart the client.
Complete the client's OAuth consent flow on first use.
Run projectctx doctor and inspect the client-specific configuration check.

The doctor result may still show incomplete CLI credential checks; those are separate from the client-managed OAuth connection.

Automatic Harvest Does Not Run

Confirm claude -p "Reply exactly OK" --model haiku succeeds. The shared scribe needs Claude's model login as well as the ProjectCtx MCP connection.
Restart the client after projectctx connect.
Approve the ProjectCtx lifecycle hook in the client's native trust flow.
Inspect ~/.projectctx/harvest/harvest.log; errors are sanitized and failed checkpoints remain retryable.
Re-run projectctx connect. Runtime updates and hook merges are idempotent.

Cursor cloud agents and hosted ChatGPT/claude.ai conversations do not run local user hooks and remain instruction-driven.

The hosted server name is project-memory and its URL is:

https://projectctx.com/mcp

Hermes / Jarvis exposes hosted tools with an mcp_project_memory_ prefix. Test that connection with:

hermes mcp test project-memory

Local MCP Server Cannot Start

The optional local stdio server command is:

projectctx mcp

It should be launched by the MCP client, not kept running in a separate shell. Confirm the client can resolve the same projectctx binary shown by:

command -v projectctx

The local server exposes:

doctor
scan_workspace
preview_code_memory
apply_code_memory

OAuth used by the hosted MCP connector is separate from CLI Code Memory authentication. If a workspace administrator issued a scoped agent token:

projectctx login --token "<scoped-agent-token>"
projectctx whoami

If the operating system credential store is unavailable, explicitly allow the protected file fallback:

projectctx login --token "<scoped-agent-token>" --allow-file-token-fallback

For temporary automation:

export PROJECTCTX_TOKEN="<scoped-agent-token>"

Remove stale overrides before retrying production:

unset PROJECTCTX_TOKEN
unset PROJECTCTX_BEARER_TOKEN
unset PROJECTCTX_API_URL
unset PROJECTCTX_WORKSPACE_ID
projectctx logout

The production REST base URL is https://projectctx.com.

Common Error Codes

Commands and local MCP tools return structured errors: { "ok": false, "error": { "code", "where", "message" } }.

Code	Meaning	Fix
`NOT_LOGGED_IN`	A scoped CLI operation has no credential.	Log in with an administrator-issued token or set `PROJECTCTX_TOKEN`.
`TOKEN_INVALID`	The cloud rejected the token.	Log out, then use a fresh scoped token.
`FILE_FALLBACK_NOT_ALLOWED`	No OS credential store is available.	Use `--allow-file-token-fallback` only on a trusted machine.
`CONFIG_PERMISSION_UNSAFE`	A token-bearing config is readable by other users.	Run `chmod 600 ~/.projectctx/config.json`.
`WORKSPACE_FORBIDDEN`	The credential cannot access the workspace.	Confirm the credential was issued for the intended workspace.
`WORKSPACE_NOT_SELECTED`	No workspace is selected for the operation.	Run `projectctx workspaces`, then `projectctx workspace use <id>`.
`API_UNREACHABLE`	ProjectCtx could not be reached.	Check connectivity and remove stale `PROJECTCTX_API_URL` overrides.
`PREVIEW_NOT_FOUND`	The preview ID is unknown.	Create a new preview.
`PREVIEW_EXPIRED`	The preview passed its TTL.	Create, review, and apply a new preview.
`IDEMPOTENCY_CONFLICT`	A key was reused for different input.	Use a new idempotency key.

Repository Scan Is Too Large Or Slow

Reduce the scan budget:

projectctx scan . --max-repos 1
projectctx scan . --max-files 8 --max-depth 2
projectctx scan . --ignore node_modules --ignore dist

Scanning is read-only and does not write cloud memory.

Code Memory Preview Or Apply Fails

Check that:

scoped CLI login succeeds with projectctx whoami;
the intended workspace is selected;
the workspace has a Repo collection;
the repository identity is unambiguous;
preview_code_memory received a non-empty markdownBrief; and
apply_code_memory uses the unexpired previewId returned to the same actor.

If the proposed content changes, create a new preview. Apply never accepts a replacement payload.