DEV Community: APX

A handoff between AI agents needs a result, not just a message

Manuel Bruña — Mon, 09 Nov 2026 21:45:46 +0000

APX is a free, open-source desktop app that runs your own team of AI agents on your machine.

Three agents can discuss a launch page and still leave you without a page. The missing piece is usually not another agent. It is an explicit definition of what the handoff must produce.

For a launch page, “design, copy and research” are activities. A stronger outcome is: a page exists at the agreed address, the claims match the product, and the links work. Independent pieces can run in parallel, but someone still has to assemble them and check the result end to end.

A useful handoff includes:

The project and relevant sources.
The exact deliverable and constraints.
One accountable owner for the piece of work.
The evidence expected: a file path, tested address, test result or a clear limitation.
The boundary between a draft, a committed change and a deployed result.

Before starting another worker, check whether the same work is already underway. Also check what assignment does in your system: if assigning a task already starts a session, separately delegating the same outcome can create duplicate work. Parallel work is valuable when the outcomes are distinct, not when two workers unknowingly start the same job.

APX's task guide describes a shared board and task conversations. Assignment normally starts a work session, with exceptions such as proposals or scheduled work. Agents are instructed to check for existing work; this is not automatic semantic duplicate detection. Treat the task conversation as a coordination aid, not a substitute for checking the artifact.

See the full handoff guide, APX tasks documentation and APX vs Paperclip comparison. APX publishes the comparison and has an interest in it; try the same task in each tool yourself. APX · Official videos

Your AI agent's project memory needs a correction test

Manuel Bruña — Mon, 09 Nov 2026 21:44:53 +0000

APX is a free, open-source desktop app that runs your own team of AI agents on your machine.

Remembering everything is not the same as being useful. A project assistant needs current decisions, constraints and enough provenance to tell where they came from. It also needs a way to correct yesterday's assumption.

A small test can reveal more than a long list of memory features:

In a project, give the agent a harmless preference and its reason. Ask it to save both.
Start a new conversation in the same project and ask a specific question that should use the preference.
Inspect the note or source if available. Correct the preference and ask again.
Record what appeared, what was missing and whether the correction was reflected.

Don't use credentials or production secrets for the experiment. One successful recall is not a guarantee that every later question will retrieve the right context. Scope, settings, the question and the model can affect retrieval. For consequential work, inspect the source before acting.

APX documents notes scoped to the person, project or agent, with controls to view and correct them. Optional automatic capture has eligibility limits: some sources, including contact chats, rooms and external sessions, are excluded. Review reduces mistakes; it does not make semantic understanding infallible.

A useful memory system should let you distinguish a durable decision from a temporary request—and show you how to fix the record when it is wrong.

Read the longer project-memory guide and memory documentation. For another documented approach, see the APX vs Hermes Agent comparison; APX publishes it and has an interest in that comparison. APX · Official videos

An AI agent needs your browser session, not your password

Manuel Bruña — Mon, 09 Nov 2026 21:44:36 +0000

APX is a free, open-source desktop app that runs your own team of AI agents on your machine.

An agent can help with a website without turning your password into another message in a chat. The important question is not simply whether the agent can open a browser. It is who signs in, which session is used and what the agent is allowed to do afterward.

Start with a narrow task: “Open this site, let me sign in, then find the invoice. Do not send or change anything.” Check the address before entering credentials. If the site asks for a one-time code or CAPTCHA, complete it yourself rather than putting the code in the conversation or asking the agent to bypass the check.

In APX, a browser handoff lets the person take over the tab for a sensitive step and return it. That depends on the desktop browser being available: a headless server browser cannot be taken over in the same way. There are other options, including approved import of an existing login for a domain and site-scoped sign-in variables. The latter can fill an allowed field without showing the value to the agent. Neither is a reason to give every site access to a credential.

A successful login is not proof that the requested job was done. Check the account, inspect the result, and review the destination before approving a consequential action. When access is no longer needed, sign out at the site and review permissions. Removing a saved variable does not necessarily close an already open session.

The practical rule is simple: use a real handoff for the secret, then verify the outcome of the work.

Read the complete browser safety guide and APX browser documentation. Explore APX and its official video channel.

An APX Interface Should Ask the Daemon, Not a Plugin

Manuel Bruña — Fri, 06 Nov 2026 12:03:18 +0000

An APX Interface Should Ask the Daemon, Not a Plugin

A new APX interface should not learn how to manage plugins. It should ask the daemon.

That sounds like an implementation detail, but it is a boundary that keeps agent behavior coherent as APX gains surfaces.

APC is the portable context layer. A repository can carry AGENTS.md, .apc/agents/, skills, and other durable project rules. APX is the daily-use runtime and tooling layer: it reads that context, runs agent work locally, and exposes it through a CLI, web panel, desktop client, and other interfaces.

The important split inside APX is just as deliberate. The architecture documents three layers: core/ for shared logic, host/ for long-running processes, and interfaces/ for surfaces. The daemon lives in host/. It is the only layer that talks to plugins. Interfaces communicate with the daemon over HTTP.

Why plugin ownership belongs in one place

A plugin lifecycle has runtime consequences. It can affect tool availability, connected services, configuration, and the current local installation. If a web panel, CLI, and desktop client each called plugins directly, each surface would need its own lifecycle code and its own interpretation of failure, configuration, and state.

That creates drift fast. A plugin might look enabled in one surface, unavailable in another, and half-configured in a third. Worse, a new interface could accidentally become a second runtime with rules that only apply there.

The daemon is the right owner because it is already the long-running APX process. It can coordinate plugin lifecycle once, keep the runtime state local, and expose one API to every surface. An interface then has a simpler job: collect a human action, call the daemon, and render the response.

A practical design test

Imagine adding a button to an APX panel that connects an integration. The button should not import a plugin package and start configuring it in the browser code. Instead, the panel sends a request to the daemon. The daemon checks the runtime configuration, performs the lifecycle work, records the local result, and returns a status the panel can show.

The same operation can then be reached from another interface without reimplementing the integration:

the CLI can call the daemon endpoint or command path
the web panel can display progress and errors
a desktop surface can trigger the same action

One operation; one runtime owner.

This also gives failures a clear home. If a connection fails, debug daemon and plugin boundary first. If the daemon reports success but one screen renders it incorrectly, debug that interface. Without this separation, every incident starts as a guessing game across several partial implementations.

What APC has to do with it

APC does not own plugin lifecycle. Its job is to preserve project context that can travel with a clone. A project may state safe, durable tool expectations in its context, but it should not turn a plugin's live local state into repository truth.

APX turns that portable context into daily work. Keeping plugin ownership in the daemon lets every interface use the same runtime interpretation of the project while keeping machine-specific operational state out of APC.

That is the useful rule:

APC carries shared project context.
APX core contains shared logic.
APX daemon owns plugin contact and runtime lifecycle.
APX interfaces stay clients, not alternate runtimes.

A thin interface is not less capable. It is more reliable because it does not need to guess how the runtime works.

A Missing APX Field Means Unknown, Not Installed

Manuel Bruña — Thu, 05 Nov 2026 21:56:20 +0000

A Missing APX Field Means Unknown, Not Installed

A small metadata field can prevent a surprisingly pushy agent experience. In an APC project, .apc/project.json may include an apx field. Its absence, or a null value, does not mean APX is installed. It means the project has not declared its APX status.

That distinction is the thesis: unknown is a state, not an invitation to assume.

APC is the portable context layer. A repository can carry AGENTS.md, agent definitions, skills, and project metadata without requiring one particular runtime. APX is a daily-use runtime and tooling layer that can read that contract, while keeping conversations, credentials, and local operational state outside the repository.

Three project intentions

A project can express a runtime relationship without turning APC into a product lock-in:

{
  "apx": "installed"
}

installed says APX is available for this project. A compatible agent can use APX commands when the task needs them.

{
  "apx": "declined"
}

declined says something stronger: keep the portable APC contract, but do not suggest or run APX for this project. It is an explicit project choice.

{
  "name": "research-notes"
}

With no apx field, the runtime status is unknown. The correct next step is a local availability check, such as apx status, only when APX would actually help with the current task. The check answers a machine question; it does not rewrite the project's intent.

Why guessing causes bad behavior

Treating unknown as installed produces brittle automation. An agent may issue commands that are unavailable, select a stale local configuration, or imply that the repository depends on a runtime its maintainers never chose. Treating unknown as declined is not better: it can hide useful tooling from a user who has APX ready locally.

The three states keep those failures separate:

Project metadata	Meaning	Safe behavior
`installed`	Project declares APX available	Use it when relevant
`declined`	Project opts out of APX	Do not suggest or run it
missing or `null`	No declaration	Check availability before assuming

This is especially useful after cloning a repository. The APC files travel with Git. An APX installation is local to a machine. Even if a teammate uses APX every day, their project metadata should not silently claim that your machine has the same runtime, daemon, accounts, or permissions.

Keep the boundary small

Do not add "apx": "installed" just because an article or example mentions APX. Add it when the project wants to declare that relationship. Do not use declined as a temporary failure marker; it communicates a choice, not a missing binary. And do not make a runtime check mutate project.json on its own. Availability changes by machine; project intent deserves review.

That small discipline lets APC remain portable and neutral. APX can still be a practical runtime for teams that choose it, but a missing field remains honest: the project has not said.

A Project Skill Can Change APX Behavior With One Name

Manuel Bruña — Sun, 01 Nov 2026 01:03:52 +0000

A skill name is a boundary, not just a label. In APX, a project-local skill with the same slug as a user-global or built-in skill wins. That is useful when a repository needs its own operating rules. It is also a reason to treat a skill name change as a real behavior change.

The precedence is deliberate

APX builds its on-demand skill catalog from three places, in this order:

<project>/.apc/skills/<slug>/SKILL.md
~/.apx/skills/<slug>/SKILL.md
APX's bundled runtime skills

The first matching slug wins. A project can therefore supply deploy/SKILL.md and make its deploy procedure available only when work is inside that project. APC carries that file with the repository, so teammates and a fresh clone can inspect the same contract. APX supplies the day-to-day runtime that discovers and loads it when relevant.

That split matters. The repository owns instructions that must travel with its code. A machine-wide directory is better for a personal convention that should apply across unrelated projects. Bundled skills remain the fallback for standard APX behavior.

A concrete example

Imagine you use a personal release skill in ~/.apx/skills/release/SKILL.md. It describes your normal checklist: verify tests, create a tag, write release notes.

A regulated service needs a different release contract. Its repository can add:

.apc/skills/release/SKILL.md

That project file can require a change ticket, a deployment window, and a rollback note. APX will use it for that project instead of the personal release skill. The global workflow remains untouched for other projects.

This is not a merge. APX does not combine two files named release; the project file replaces the lower-priority match. If the project version omits an important step from the global version, that step is absent in the resolved project skill.

The common mistake: accidental shadowing

A generic name such as review, test, or deploy makes collisions easy. An engineer may create a project skill with a familiar slug, expecting to add a few local details, but actually replace the existing guidance entirely. The result can look inconsistent: the same request produces different behavior in different projects.

Avoid that surprise with a small review routine:

Use a shared slug only when replacement is intentional.
Give additive or experimental guidance a distinct name, such as payments-release or api-contract-review.
State the scope in the skill description so the catalog explains when it applies.
Review the complete project skill, not only its diff against a global counterpart.

Portable override, local runtime

The project skill belongs in APC because it is part of the repository's durable agreement. It can be reviewed in Git alongside the code it governs. APX can then resolve that agreement in the active project without putting personal global skills, sessions, or private runtime state into the repository.

That is the practical value of precedence: one project can deliberately own its workflow without turning every local customization into a global rule.

Load Nested AGENTS.md Rules at the Folder Boundary

Manuel Bruña — Fri, 23 Oct 2026 13:43:24 +0000

Load Nested AGENTS.md Rules at the Folder Boundary

A project needs shared instructions, but it does not need every instruction in every turn. The useful rule is: put folder-specific guidance in that folder's AGENTS.md, then load it when work reaches that folder.

That sounds like a small organization detail. It is actually a context-quality boundary. If a repository-wide agent prompt carries every rule for the mobile app, deployment scripts, data migration, and marketing site, most of those rules are irrelevant most of the time. The important instruction becomes harder to notice precisely when it matters.

Keep root guidance truly shared

An APC project keeps portable context in the repository. Root AGENTS.md is the place for rules that apply across the project: conventions, commands, safety constraints, and an index of the project-level agent setup. It should answer questions that matter no matter which directory a task touches.

For example, a root file might say:

Run the repository test suite before changing shared packages.
Do not commit credentials or generated runtime state.
Use the documented release workflow.

Those are project facts. They are useful to a compatible tool from a fresh checkout, and they stay useful whether the next edit is in api/, web/, or infra/.

Put local rules next to local work

Now consider a migration directory that needs a special ordering rule, or a service folder that has a separate test command and an external API contract. Those instructions should not become permanent background for an unrelated documentation edit. Give the directory its own AGENTS.md instead:

repo/
├── AGENTS.md
├── api/
│   ├── AGENTS.md
│   └── migrations/
└── web/
    └── AGENTS.md

The api/AGENTS.md can explain migration safety and API checks. The web/AGENTS.md can describe component conventions and browser tests. Each file has a narrow owner: the folder beneath it.

This is not an excuse to hide global policy in a deep directory. A rule belongs there only when its scope really starts there. A ban on secrets belongs at the root; a warning about a destructive database fixture can belong with the fixture. Scope should follow the work boundary, not the writer's desire to keep a file short.

Attach instructions when the tool crosses the boundary

APX makes this structure operational. For a project turn, it supplies the project AGENTS.md and identifies subfolders with their own instruction files. When a tool first touches one of those folders in that turn, APX attaches the folder's rules to the tool result. The agent receives the local rule at the moment it has evidence that the task reached that part of the tree.

That timing matters. Imagine a request to update a landing-page headline. The agent should not begin with database migration instructions. If the same task later changes an API schema, the API guidance appears when the work enters api/. The context grows with the actual path of work instead of arriving as an unfiltered manual.

Portable contract, local execution

APC provides the portable contract: committed AGENTS.md files travel with the repository and can be reviewed like other project decisions. APX is the daily-use runtime: it selects relevant project context during a turn while keeping conversations, tool history, and private runtime state local.

Together, they support a simple habit: write root rules for the whole project, write nested rules for real local boundaries, and let the runtime reveal local guidance when the task crosses that boundary. Less prompt noise is not merely tidier. It gives the right instruction a better chance to govern the right action.

A Runnable Project Needs Both Instructions and Identity

Manuel Bruña — Thu, 22 Oct 2026 11:57:59 +0000

A Runnable Project Needs Both Instructions and Identity

A folder is not automatically an agent project. It may contain code, notes, and a useful prompt, but an agent runtime still needs two answers before it can treat that folder as durable work: what guidance applies here, and which project is this?

APC and APX make those answers explicit with two small files:

AGENTS.md holds shared instructions: conventions, constraints, commands, and project-specific context.
.apc/project.json holds stable metadata, including the project name and a stable apx_id when APX manages the project.

That pair is a practical boundary. In APX, apx project add reads both files. If either is missing, registration stops rather than guessing that a random directory is a complete project.

Why one file is not enough

An AGENTS.md without metadata can explain how work should happen, but it does not give the runtime a stable identity for its local state. Two checkouts can have similar instructions; the runtime still needs to know which local project store belongs to this one.

A project.json without instructions has the opposite problem. It can name a project, but it cannot tell an agent the repository's rules, safe boundaries, or expected workflow. Identity without guidance turns registration into a label, not a usable contract.

The two files also keep responsibilities clear. APC is the portable context layer: commit the shared contract with the repository. APX is the daily-use runtime: it uses that contract while keeping sessions, conversations, messages, caches, task logs, and machine-specific configuration under ~/.apx/projects/<apx_id>/.

A small, reliable setup

Start with a repository root like this:

my-project/
├── AGENTS.md
└── .apc/
    └── project.json

Keep AGENTS.md focused on guidance that teammates and compatible tools should share. Keep project.json focused on stable metadata. Do not put API keys, raw session logs, or private runtime memory in either file.

Then register the project explicitly:

apx project add .

APX can link the committed project definition to its local runtime directory through apx_id. If the repository moves and the runtime needs to re-scan the on-disk contract, use:

apx project rebuild <id|name|path>

The important detail is not the command. It is the refusal to invent missing context. A runtime that silently registers a folder without instructions might use generic behavior where project rules mattered. A runtime that invents an identity can attach local history to the wrong work boundary.

The useful rule

Before you ask an agent runtime to own ongoing work, give the project both instructions and identity. AGENTS.md says how contributors should act. .apc/project.json says what durable project definition they are acting within.

That is the division of labor: APC keeps the contract portable and reviewable; APX makes it operational on one machine without committing private runtime state back into the repository.

Create a Specialist Agent Only After Its Work Boundary Is Stable

Manuel Bruña — Wed, 21 Oct 2026 12:03:08 +0000

Create a Specialist Agent Only After Its Work Boundary Is Stable

Adding an agent is easy. Giving it a durable job is harder.

The useful rule is: create a specialist only when its work boundary is stable enough to write down, review, and reuse. Until then, keep the work with a main agent and improve the shared project guidance.

This is where APC and APX have different jobs. APC is the portable layer: it keeps a project's shared rules, structured agent definitions, reusable skills, and safe curated context in the repository. APX is the runtime layer: it makes those agents useful in daily work through conversations, tools, routines, and local state. A runtime can start an agent immediately; that does not make the agent design ready to travel.

A role is not a label

A weak specialist is only a name: researcher, writer, or support. It sounds organized, but it does not tell another person—or another runtime—what the agent owns, what it must consult, or where it must stop.

A stronger role has a boundary. Consider a support workflow:

The agent handles first responses and routine refund triage.
It uses the project's refund policy and escalation skill.
It escalates large refunds rather than approving them.
It writes in the project's customer-facing language.

That is a contract, not a personality. It can live in an APC agent definition and linked skills, be reviewed in a pull request, and be read by compatible tooling after a fresh checkout.

Start with one repeated decision

Do not split work because a team diagram looks better with more nodes. Split it when one decision pattern keeps returning and has clear inputs, constraints, and handoff conditions.

For example, a main agent may initially answer support questions, check policy, and call for human review when needed. After that pattern is repeated, the project can extract a support specialist. The extraction should preserve the decision boundary:

Inputs: customer request and account context
Rules: published refund window and escalation threshold
Output: response, or a clearly named escalation
Not owned: legal negotiation or approval beyond the threshold

This small shape prevents a common mistake: creating a specialist that overlaps every other agent and silently makes choices outside its intended role.

Put durable detail in the right place

APC gives the boundary a portable home:

AGENTS.md holds project-wide rules.
.apc/agents/<name>.md states the specialist's role and instructions.
.apc/skills/ holds reusable procedures shared by one or more agents.
.apc/ excludes raw conversations, credentials, and runtime caches.

APX can then use that contract while keeping the daily machinery local: sessions, messages, private runtime memory, provider credentials, and tool execution belong to the runtime rather than the repository.

That separation matters during change. Updating a support rule is a project decision. It should be visible in the portable contract. A chat transcript from yesterday is runtime evidence, not the new source of policy.

A practical test before adding an agent

Before creating a specialist, write four lines: purpose, inputs, constraints, and handoff. If those lines stay vague, the work is probably still main-agent work. If they are precise, the project has something worth encoding in APC.

Then APX can run the agent in the places people actually work. The runtime gives the role a daily presence; APC keeps the role from becoming a local, unreviewed convenience.

A good specialist is therefore not another prompt to maintain. It is a portable promise about a narrow kind of work.

An APX Approval Scope Is a Real Boundary, Not a Convenience Button

Manuel Bruña — Tue, 20 Oct 2026 12:04:30 +0000

An APX Approval Scope Is a Real Boundary, Not a Convenience Button

A permission prompt looks small: approve or deny. But the important question is not only whether an agent may run a tool. It is how far that approval reaches.

APX treats that reach as an explicit boundary. A one-time approval is one execution. A session approval belongs to one conversation. An always approval belongs to one agent, including later conversations and a restart. Those are different decisions, so they must not blur into one friendly-looking button.

The dangerous shortcut

Many agent products make approval feel like a binary switch. A person allows a harmless read, then later discovers that the agent stopped asking. The original decision silently became broader than the person intended.

That is especially risky when a tool can receive different arguments over time. Approving a request to read one note is not necessarily approval to read every note, call a different endpoint, or let a second agent act in another chat.

APX starts from the narrowest useful default: once. The approval runs the pending tool call, then disappears. The next request creates a new prompt. No permanent grant is created as a side effect.

Agent: use notes.search({ query: "release checklist" })
Human: approve once
APX: runs that call

Agent: use notes.search({ query: "customer contracts" })
APX: asks again

The second prompt is not friction by accident. It preserves a chance to notice that intent or data changed.

Choose scope deliberately

APX exposes three scopes for an eligible approval:

once: only pending call; no saved grant.
session: later turns in same chat can use tool, even when arguments change. Other chats still ask. Revocation can remove grant.
always: same agent can use tool across its chats and after runtime restart. Other agents still ask.

This makes a practical review habit possible. Start with once while learning what an MCP tool does. Move to session when a single conversation needs repeated work. Choose always only when tool, agent, and long-term purpose are all known and acceptable.

The boundary is not merely user-interface language. APX tests that a session grant does not unlock another chat, that an always grant remains tied to its agent, and that revocation restores a prompt. It also rejects attempts to turn a denial into a wider grant; agents themselves cannot grant permissions.

Separate tool trust from project context

This is runtime policy, not portable project context. APC carries the repository-owned contract: AGENTS.md, .apc/, agent definitions, skills, and durable team guidance. It can say that a project uses a particular workflow or needs careful handling.

APX is the local runtime that executes a particular conversation. Approval records, pending prompts, and revocations describe a local operational decision. They should not become a hidden rule inside a portable repository. A fresh checkout should inherit documented project intent, not someone else's unreviewed tool grant.

That separation also keeps responsibility clear. APC can explain why a project needs a tool. APX asks a human whether this agent may use it now, and for how long.

A small rule that scales

Treat every broader scope as a new claim:

This call is safe now.
This conversation can repeat it.
This agent may keep doing it later.

Each step needs more evidence than the last. A scope selector that reflects that difference turns permission from a vague comfort signal into an auditable control boundary.

APC keeps project intent portable. APX keeps operational authority local, explicit, and revocable. That is slower than silently upgrading one approval into permanent trust—but much easier to trust in real work.

An Interrupted Tool Call Needs an Explicit Ending

Manuel Bruña — Mon, 19 Oct 2026 12:05:11 +0000

An Interrupted Tool Call Needs an Explicit Ending

An agent can begin a tool call and lose its turn before receiving a result. A browser closes, a provider times out, a runtime restarts, or a person stops the work. That gap is ordinary. Pretending it never happened is not.

The useful rule is small: an interrupted tool call needs an explicit ending in conversation history. APX follows that rule when it repairs chat history. Rather than leaving an unanswered request dangling, it records that the tool was not run because the turn was interrupted.

Why a dangling call is a problem

Tool-using model APIs expect a strict sequence. An assistant message requests a tool, then a corresponding tool result returns. If history contains the first half but not the second, the next turn inherits an ambiguous state.

Did the browser search happen? Did a file get written? Is a retry safe? A model should not have to guess. Nor should a later reader infer success from an assistant message that only asked for an action.

Consider a short history:

User: Check the deployment dashboard.
Assistant: calls browser_text({ url: ... })
[process interrupted]
User: What did it find?

Without repair, the last question invites invention. A plausible answer may sound like a dashboard summary even though no result exists. That is worse than a visible interruption because it turns missing evidence into a claim.

Repair the structure, not the story

APX's runtime-history repair logic starts at a real user item, ignores orphaned tool results, and checks each assistant tool call for its matching result. When a new non-tool item arrives—or history ends—any unanswered call is closed with this explicit record:

not run: the turn was interrupted

The repaired version becomes:

User: Check the deployment dashboard.
Assistant: calls browser_text({ url: ... })
Tool: not run: the turn was interrupted
User: What did it find?

That line is deliberately narrow. It does not claim the action failed in the outside world. A request might have reached an external service before the runtime lost contact. It only says APX has no completed tool result for this turn.

This distinction matters for retries. A safe next step may be to inspect current state, ask the user, or run an idempotent check. It is not automatically “do it again.”

Keep portable context out of the repair

This is runtime work, not a change to project context. APC keeps the portable contract: AGENTS.md, .apc/ metadata, agent definitions, skills, and safe shared guidance in a repository. A compatible tool can read that contract from another checkout.

APX is the daily-use runtime. Its chat history, tool-call records, sessions, and interruption markers are local execution state. They must describe what happened in a particular conversation, but they do not belong in a portable project contract.

The boundary makes recovery easier to reason about. APC still tells an agent what project rules and skills apply after a restart. APX separately tells it whether the last tool call produced evidence. One layer supplies durable intent; the other preserves honest operational facts.

A practical recovery habit

When a tool-backed turn is interrupted, keep three questions separate:

Was a tool requested?
Did APX receive a matching result?
What check is safe before continuing?

Only the second question has a certain answer from the repaired history. The third depends on the operation: inspect a read-only dashboard, check a task status, or ask before repeating a write.

An explicit interruption marker is not glamorous, but it prevents a subtle class of agent mistakes. APC keeps project context portable. APX keeps execution history accountable. The next turn can then continue from evidence instead of from a gap that looks like success.

Name the Project Before the Conversation Drifts

Manuel Bruña — Sun, 18 Oct 2026 12:03:26 +0000

Name the Project Before the Conversation Drifts

A useful agent conversation needs more than a capable model. It needs a clear answer to a smaller question: which project does this turn belong to?

If that answer changes invisibly, an agent can read the wrong rules, suggest the wrong specialist, or look at the wrong local history. The failure is subtle because the reply may still sound reasonable.

APX makes project selection a per-turn decision. It uses the project already active on the surface, otherwise a project named in the message, otherwise the project named earlier in that conversation. That order gives a practical rule: when the project matters, name it before the conversation has a chance to drift.

A project is more than a folder

In APC, a project carries portable context: AGENTS.md, agent definitions, skills, shared MCP hints, and project metadata under .apc/. That is the contract a compatible tool can read from a checkout.

APX is the runtime layer. It uses the selected APC project to decide which agents, MCP servers, root guidance, and durable agent memory belong in the turn. Its conversations, sessions, task logs, and private runtime state remain local under ~/.apx/.

So selecting a project is not a cosmetic label in a chat sidebar. It is the boundary that tells APX which portable contract and which local working state apply.

Let the surface decide when the surface is clear

A project chat or code session already has useful scope. If you open the storefront project and ask for a checkout review, APX can use that project directly. The work surface and the project contract agree.

That is the best case for sustained work: stay in the project surface while the task belongs there. The conversation gets its agents and guidance from the same project whose files the work will touch.

But not every request begins there. A person might be in a general chat, replying from a message channel, or returning to an old conversation after changing tasks. In those cases, make the target explicit in ordinary language:

For storefront, review the release checklist.

In the data-pipeline project, summarize the failed import.

The project name is short context with a large effect. It avoids relying on a previous topic that may no longer be relevant.

Do not turn conversational carryover into ownership

Using a project named earlier in the same conversation is helpful for follow-up questions. After discussing storefront, a later “what should we test first?” can keep the same scope without repeating the name every turn.

That convenience should not become hidden ownership. Switch deliberately when the work changes:

Now for data-pipeline: list likely causes of yesterday's import failure.

A new project name is better than assuming that the last active project remains correct. It gives the next turn an observable boundary and gives a reviewer a simple explanation for why certain context was present.

Keep chat scope and command scope aligned

A terminal command has the same problem in a different form. When the current directory is not a reliable signal, pin the project:

apx messages tail --project storefront
apx agent list --project data-pipeline

The message-level name and the command-level --project flag serve one idea: state the intended owner at the moment it matters. Neither copies project rules into runtime history, and neither makes private session data portable. They only select the correct boundary.

A small habit that prevents quiet mistakes

Use the project surface for ongoing project work. Name the project in a neutral conversation when scope is important. Repeat the name when the subject changes. Pin commands when the shell location is incidental.

APC keeps the project contract portable. APX makes that contract useful turn by turn. Naming the project is the small bridge between them—and it is easier to trust than a guess based on whatever the conversation happened to discuss last.