Pin the APX Project Before You Run the Command

The current directory is a convenient default. It is not a reliable identity.

That is why APX accepts --project <name|id|path> on most project-aware commands. The flag is a small guardrail: it makes the target explicit before APX reads agents, chooses runtime state, or writes a task, routine, message query, or configuration change.

APC is the portable context layer: AGENTS.md and .apc/ describe a project in a repository. APX is the local runtime and tooling layer: it uses that context while keeping sessions, messages, and operational state on the machine. A command needs to know which APC project it serves.

The helpful default

When no project is named, APX walks upward from the current directory looking for an APC root. If it finds a registered project, it uses it. If it finds an APC project that is not registered yet, it can register it. If it finds neither, some commands fall back to APX's built-in default workspace.

That behavior makes the common case pleasant:

cd ~/code/storefront
apx agent list
apx run reviewer --runtime codex "Review the checkout changes"

Working from the project root is a good default because the shell location, source files, and APC contract all point to the same place.

Where the default becomes risky

Now imagine a terminal that is not in the intended repository: a monorepo parent folder, a notes directory, a temporary checkout, or a shell reused after another task. The command can still be syntactically valid while targeting the wrong project or the default scratch workspace.

That is especially costly for commands that change state. A routine created in the wrong project runs with the wrong agents and context. A project config update changes a different local runtime profile. A message search can make you inspect the wrong evidence trail.

The failure is not that APX cannot infer a project. The failure is asking inference to carry authority when you already know the target.

Use an explicit pin for cross-project work

Use --project whenever your shell location is incidental rather than meaningful:

# From any directory, inspect one project's agent definitions
apx agent list --project storefront

# Keep routine ownership unambiguous
apx routine add daily-review --project storefront --schedule "0 9 * * 1-5"

# Query runtime evidence for that project only
apx messages tail --project storefront

# Run a coding agent against the intended APC contract
apx run reviewer --runtime codex --project storefront "Review the checkout changes"

APX accepts a numeric id, an exact project name, an absolute path, or a relative path resolved from the current directory. If a short name matches more than one registered project, it refuses the ambiguity instead of choosing silently. apx project list is the quick way to inspect available names and ids.

The important distinction

--project does not turn runtime state into portable context. It does the opposite: it preserves the ownership boundary.

APC remains the committed definition of storefront: agents, skills, shared MCP hints, and project rules. APX uses the selected project's stable apx_id to locate its local sessions, messages, tasks, routines, and machine-specific configuration.

So one explicit flag connects two layers without mixing them:

• APC answers what project context should travel.
• APX answers which local runtime state belongs to that project today.

A practical rule

Trust the current directory when you deliberately opened a shell inside one project. Pin --project when working from a shared terminal, automation, another repository, or a directory where project inference would be a guess.

This is not extra ceremony. It is a short, readable record of intent beside the command that matters. In agent tooling, the safest target is often the one you name.