APX

The apx agent list command can use the --project flag to specify a project, for example apx agent list --project data-pipeline.

The apx messages tail command can use the --project flag to specify a project, for example apx messages tail --project storefront.

APX's conversations, sessions, task logs, and private runtime state are kept locally in the ~/.apx/ directory.

Explicitly naming the project is regarded as the lowest-cost means of correcting context drift, because it provides an observable, reviewable boundary signal at every turn.

Project names are short yet efficient context, avoiding reliance on old topics that may no longer be relevant.

Ongoing project work should use the project interface; when scope is involved in a general conversation, proactively name the project; when the topic changes, repeat the project name.

When a project matters, name it before the conversation drifts (a practical APX principle).

For an existing APC project, you can simply register it via `apx project add /path/to/project`.

You can use `apx agent list --project my-project` and `apx exec reviewer --project my-project "Review the release notes"` to explicitly specify the target project when the current directory is unreliable.

APX's runtime state (conversation records, sessions, task logs, credentials, machine-specific settings) is essentially local state, usually kept in the `~/.apx/projects/<apx_id>/` directory, with its lifecycle managed by APX.

APX ships with a built-in project named `default`, located at `~/.apx/projects/default/`, used to store scattered work that does not belong to any project.

The default workspace is shared across contexts, with no repository contract, committable agent definitions, or portable boundaries, so it is unsuitable as a long-term home for real project work.

A practical rule is: use the `default` project for drafting work; when the work belongs to a project, an APC project should be created or registered.

When work begins to require shared rules, repeatable agent roles, reusable skills, or review in version control, it already has project form, even if it is not yet a Git repository.

An APX project is a directory containing `AGENTS.md` and `.apc/project.json`.

For a new project, you can run `apx init` and `apx project add .` in its directory to initialize and register it.

APX's design records task workflow columns separately from execution evidence (execution view).

APC provides a portable, version-controllable instruction contract that travels with the repository and describes 'what success should look like'; APX handles the instantaneous, local, non-portable runtime facts of 'what is actually happening right now'.

APX finds the runtime session related to a task through task comments that carry session identity and path, rather than scanning all agent history.

APX keeps execution evidence separate from task closure, preventing agents from translating 'the command finished executing' into 'the work has been accepted'.