The APX Default Project Is a Scratchpad, Not a Workspace

Agent tools need somewhere to put work when no project is active. APX has that place: its built-in default project under ~/.apx/projects/default/. It lets the super-agent handle general, unscoped work without first asking someone to create a repository.

That convenience becomes dangerous when default quietly turns into the home of real project work. A default workspace is shared across contexts. It has no repository contract to carry intent, no committed agent definitions, and no portable boundary another machine can pick up. It is a fallback, not ownership.

The useful rule is simple: use default for scratch work; create or register an APC project when work belongs to a project.

What scratch work looks like

A few examples fit the default project well:

• Ask APX to explain a command, compare two ideas, or make a temporary checklist.
• Start a personal conversation not attached to a codebase, client, or team.
• Try a model or a tool before deciding whether it belongs in a project.

Those actions need local runtime state, but they do not yet need a durable project agreement. A transcript, a short-lived task, or an experiment can remain local to APX.

The boundary changes when the work needs shared rules, repeatable agent roles, reusable skills, or review in version control. Then the work has a project shape even if it is not a Git repository.

Give durable work an explicit home

An APX project is a directory containing AGENTS.md and .apc/project.json. The APC files hold portable project context: agent definitions, skills, MCP hints, and project metadata. APX registers that directory and stores its runtime-only state separately under ~/.apx/projects/<apx_id>/.

For a new project, start in its directory:

apx init
apx project add .

For an existing APC project, registration is enough:

apx project add /path/to/project

After that, target it deliberately when your current directory is not reliable:

apx agent list --project my-project
apx exec reviewer --project my-project "Review the release notes"

That choice answers two separate questions. APC answers what the project means and which guidance can travel with it. APX answers where local conversations, sessions, task logs, credentials, and machine-specific settings belong. Neither side needs to pretend it owns the other.

Why implicit ownership causes trouble

Suppose a team uses the default project for release planning because it is already open. The plan may look available in the panel, but a teammate who clones the repository cannot discover its rules or agent roles from the repository. Later, unrelated personal chats and project history also share one runtime bucket. Context becomes hard to review, move, or clean up safely.

Putting the same work in an APC project does not make every conversation portable. It should not. Raw sessions and private runtime memory still stay local. What moves is the contract: the project instructions, named agents, reusable skills, and safe shared metadata. A second machine can register the project and build its own local runtime state around that contract.

Make the fallback visible

The default project is valuable precisely because it is temporary and unowned. Do not delete or over-engineer it. Just avoid giving it work that needs a durable boundary.

When a task is only a question, scratch is fine. When it needs teammates, review, repeatability, or a future checkout, give it a project directory and APC context.

A fallback keeps APX helpful. An explicit project keeps the work understandable.