DEV Community: Manuel Bruña

Give APC Rules a Useful Counterexample

Manuel Bruña — Tue, 15 Sep 2026 13:07:54 +0000

A project rule can be clear about its preferred behavior and still leave its boundary unclear. One small counterexample can show where the rule stops applying.

My thesis: when an APC instruction is easy to overgeneralize, add a nearby case that looks similar but requires a different decision. This gives reviewers a concrete way to check the instruction's meaning.

APC is the portable context layer: repository-owned guidance in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer that works with that context. Neither distinction removes the need to write instructions that a new contributor can interpret correctly.

Show the boundary, not just the happy path

Consider a hypothetical repository with this instruction:

Every user-visible label starts with a capital letter.

An agent could reasonably apply that sentence to every string rendered on screen. That would include command names, file paths, and fragments inserted into a longer sentence. The instruction needs a sharper definition of “label.”

A more useful version might say:

Start interface labels with a capital letter: buttons, headings, and tabs.
Example: "Project memory".

Preserve literal commands and paths exactly.
Counterexample: displaying `apx restart` does not make it "Apx restart".

Sentence fragments follow the sentence they join.

The counterexample does useful work because it is close to the rule. Both cases involve text on screen. The difference is whether the text names an interface element or represents a literal value.

This example is grounded in the APX repository's engineering guide, which distinguishes labels, sentence fragments, and data such as commands and slugs. The shortened wording above is an illustration, not a replacement for that repository's full contract.

Choose a plausible mistake

“Do not capitalize binary files” would be a weak counterexample here. It is too far from the decision an agent is likely to face.

A useful counterexample has three properties:

It shares the feature that could trigger the rule: here, visible text.
It identifies the distinguishing property: here, an exact command spelling.
It states the correct action: preserve the literal value.

The same pattern works in other domains. A hypothetical instruction to retry read failures could distinguish a failed read from a write whose outcome is unknown. A rule to normalize display names could explicitly preserve stable identifiers. Those are writing examples; each repository must define its actual behavior and constraints.

Avoid building a catalog of every possible exception. Choose the nearest misunderstanding that changes the outcome. If many exceptions are necessary, rewrite the main rule or split it into narrower rules.

Keep examples beside the instruction

The APC rules specification separates the root contract in AGENTS.md from reusable or path-scoped guidance in .apc/rules/. It also asks that rules remain concise, concrete, and reviewable.

Put the boundary example next to the relevant rule, wherever that rule belongs. A counterexample buried in a separate chat will not help a reader who receives only the instruction. Duplicating it across several files creates another maintenance problem.

During review, ask someone to classify two cases: one that should follow the rule and one that should not. If reasonable readers disagree, the text still needs work. This is a proposed review technique, not an APC validator or an APX feature that automatically checks prose.

Executable checks remain valuable where the distinction can be tested. The written rule explains the intended boundary; a test can catch a specific violation. An example alone does not enforce anything.

Portable context should carry enough meaning to survive a change of reader. Sometimes the most useful addition is one sentence showing exactly where an otherwise sensible rule stops.

Explore Agent Project Context on GitHub.

APX Community is now on Discord: build and orchestrate agents together

Manuel Bruña — Mon, 14 Sep 2026 17:39:10 +0000

APX Community now has a home on Discord.

APX (Agent Project eXecutable) is a local runtime, CLI, and web admin for AI agents, built on the APC protocol. It brings portable project context to life while keeping runtime sessions and private state local.

What you’ll find in the community

Help with APX setup, runtimes, engines, and the local daemon
Practical MCP workflows and integrations
Multi-agent patterns, experiments, and lessons learned
APC discussions: portable context, agent roles, skills, and project memory
Roadmap updates, release news, and community showcases
Spanish and English spaces

Whether you use Codex, Claude Code, OpenCode, Aider, Gemini CLI, or local models, you’re welcome. Bring questions, show what you’re building, and help shape an open, local-first agent ecosystem.

👉 Join APX Community: https://discord.gg/vxdZuT5WuE

Quick start

npm install -g @agentprojectcontext/apx
apx setup
apx init

Learn more: https://agentprojectcontext.github.io/apx/

GitHub: https://github.com/agentprojectcontext/apx

Why I Give APX Group Conversations a Finite Budget

Manuel Bruña — Mon, 14 Sep 2026 13:04:48 +0000

I want agents to talk to each other without making me carry every message between them. That is part of what I am building in APX, the local runtime around APC's portable project context. But connecting two agents creates a question that a normal chat can hide: how much work did I authorize by sending one message?

My answer is that the conversation needs a finite execution budget. A room should be able to continue a useful exchange, but each new speaker cannot quietly receive an unlimited invitation to work.

This build note is about that multiplication, and the deliberately small piece of orchestration that contains it.

A mention becomes another turn

In APX's group turn resolver, a human message seeds a queue of speakers. If I mention an agent, that agent gets a turn. If I mention several, they are queued in mention order. If I mention nobody, the first agent in the room starts.

The interesting part comes after the first reply. An agent can mention another participant and bring that participant into the exchange. Someone who already spoke can speak again. That allows an actual back-and-forth instead of a fixed round where everyone delivers an isolated opinion.

Here is an illustrative exchange, not a transcript:

Owner: @builder explain the proposed parser change.
Builder: The change handles empty input. @reviewer check the edge cases.
Reviewer: Whitespace-only input needs a decision. @builder clarify that case.
Builder: Treat whitespace-only input as empty, and test both forms.

There is useful work in the second pass. Preventing an agent from ever speaking twice would remove that possibility. But allowing the same two participants to keep summoning each other also makes a loop easy to construct.

The resolver excludes self-mentions and avoids adding someone who is already waiting in the queue. Neither rule prevents alternating replies forever. The current default ceiling does: one human message can produce at most ten agent replies.

I think of that ceiling as an execution boundary, not a target. A good conversation can finish after two replies. Reaching ten does not prove that the problem is solved.

Ten replies can mean much more than ten messages

The next detail matters more than the room's visible message count: a speaker's reply can involve a full tool loop.

A short paragraph at the end might follow several tool steps. Multiplying the number of speakers therefore multiplies potential work beneath the conversation. A room that looks quiet can still be expensive to run.

APX's current defaults give group speakers a tool-loop budget of 50 iterations. The group cascade allows ten replies. That makes the simple default envelope:

10 agent replies × 50 iterations = 500 iteration slots

This is not a token estimate, a price quote, or a benchmark. An iteration is not interchangeable with a dollar amount or a single external side effect. The calculation tells me where execution can multiply; it does not tell me what a particular conversation will cost.

The ordinary web-chat default is 1,000 iterations. Reusing that budget for every group speaker would make the corresponding envelope 10,000 slots. That is why I do not treat a group room as merely a normal chat with more names in the sidebar.

These are defaults in the current implementation. The per-speaker budget is configurable through super_agent.group_max_iters; setting it to zero selects the built-in default. The comparison above is not an enforced global quota across arbitrary custom settings.

A useful stop has to stop the queue

A finite ceiling is only one way a conversation ends. The owner also needs to be able to interrupt it.

The resolver accepts an abort signal and checks it between speakers. That sounds minor until you imagine stopping the current agent while nine more replies remain eligible to run. Ending one reply would not express what the owner meant by stopping the room.

The active run needs its own cancellation handling; the resolver's responsibility is to avoid starting the next speaker after cancellation. I like this separation because it makes the boundary concrete. The queue owns turn-taking. The agent runner owns the execution it started.

The same separation makes the orchestration easier to examine. The resolver receives a runAgent callback instead of embedding a provider call. Mention parsing and queue behavior can be exercised without asking a live model to produce the right sentence on demand.

That is a design decision I want to keep: model output influences who speaks next, while ordinary code decides whether another turn may start.

What I would ask a room to produce

For a parser review, I would ask for a bounded outcome: identify the unresolved input cases and return a proposed decision for each. The room can use cross-mentions to challenge an answer, but the deliverable remains something I can inspect.

If one participant needs a long implementation session, I would continue that work in its own chat. The group is useful for resolving a question between participants; it does not have to absorb every subsequent task.

There is a tradeoff here. A finite budget can interrupt a worthwhile discussion. Increasing it may be reasonable for a particular deployment. But I want that to be an explicit choice, made while looking at the cascade and per-speaker budgets together.

APC gives me a place for portable agent definitions and project instructions. APX has to decide how those agents actually run. Group conversations make that distinction tangible: defining a useful role does not define how many times it may be invoked by another role.

The lesson I am taking from this implementation is simple: autonomy includes deciding when another turn is allowed. Getting agents to answer each other is only half the feature. Giving the exchange a finite boundary is what makes it manageable.

Implementation references: group turn resolver, tool budget constants, and super-agent documentation source.

Give Temporary APC Instructions an Exit Condition

Manuel Bruña — Mon, 14 Sep 2026 12:03:42 +0000

Temporary project instructions need an exit condition. Otherwise, an exception written for a migration can keep steering agents long after the migration ends.

Imagine a repository moving from a legacy invoice parser to a replacement. During the transition, agents should keep both implementations and test their outputs against the same fixtures. Six months later, the old parser is gone, but a project instruction still says to preserve it. The instruction is readable, versioned, and wrong.

APC is the portable context layer: project guidance lives in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer that works with that context. Portability makes an instruction available across tools; it does not make yesterday's exception correct today.

Make the condition visible

Consider this hypothetical addition to a repository's AGENTS.md:

Keep the legacy invoice parser. Run both parsers when changing invoice handling.

That leaves the next contributor guessing. Is the old parser a permanent compatibility requirement? A rollback mechanism? An unfinished experiment?

A more useful instruction records the temporary boundary:

While the invoice parser migration remains open:
- Keep the legacy parser available for rollback.
- Compare both parsers using the committed compatibility fixtures.

Retire this instruction when the migration owner accepts the replacement
and removes the legacy rollback path. Update this section in that same PR.

The second version does not automate the decision. It tells a reviewer what decision must happen before the instruction can disappear. The fixture names, owner, and acceptance record would need real project-specific references in an actual repository.

A calendar deadline alone is weaker. Reaching Friday does not prove the replacement works. A date can prompt a review; an observable project condition explains whether the exception still applies.

Keep the permanent rule separate

The lasting requirement might be “preserve invoice compatibility.” Running two parsers is only one temporary way to establish that compatibility.

Write those ideas separately. When the migration ends, remove the dual-parser procedure while keeping the compatibility requirement and its relevant tests. Otherwise, deleting the temporary instruction can accidentally delete the reason the team needed it.

This fits APC's definition of project context: information that remains meaningful across editors, machines, and runtimes. A temporary instruction can still be shared project guidance, provided its scope and retirement condition are explicit. Durability should mean maintained knowledge, rather than text that nobody touches again.

Review retirement alongside implementation

For a migration PR, I would add a short review question: which existing instructions become false if this change lands?

Check the root contract, relevant agent definitions, and reusable instructions that mention the old behavior. Follow references instead of searching only the file edited during implementation. If the migration is partial, narrow the instruction to the remaining legacy path and retain its exit condition.

The APX repository's engineering guide includes a related practice: comments describing migrations should change when those migrations finish or are abandoned. Applying that same maintenance habit to project guidance is a proposed review workflow, not a claim that APC or APX automatically detects stale instructions.

A useful completion note can stay small:

Legacy parser removed after acceptance.
Temporary dual-parser instruction retired.
Compatibility requirement and replacement tests retained.

That note explains why guidance changed without copying the migration's entire conversation into the repository.

Version control preserves old decisions when you need to investigate them. Active context should explain what applies now. Giving temporary instructions an exit condition helps the next agent tell the difference.

Explore the portable context format in Agent Project Context on GitHub.

Moving a Folder? Review Your APC Rule Globs

Manuel Bruña — Sat, 12 Sep 2026 12:04:01 +0000

A folder rename can leave your application healthy while quietly disconnecting its agent instructions. Imports resolve, tests pass, and the rule file still reads well. Its path selector now points at yesterday's repository.

Treat a directory move as a change to the context map: review the relevant APC rule globs in the same pull request.

APC is the portable context layer, keeping project instructions in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer around that context. This example concerns the project-owned rule, so the durable fix belongs in APC.

The instruction survived; its target moved

Imagine a project with payment handlers under src/payments/. Its .apc/rules/payments.mdc contains this illustrative rule:

---
description: "Payment handler conventions"
globs:
  - "src/payments/**/*.ts"
alwaysApply: false
---

- Preserve the existing retry behavior when changing a handler.
- Include a duplicate-request case when testing a write operation.

The APC rules specification describes path-scoped MDC files and distinguishes them from the repository-wide contract in AGENTS.md. Actual selection and projection depend on the compatible consumer; the format alone does not prove a particular tool loaded the rule.

Now move those handlers to packages/billing/src/. The old selector no longer names their location. Nothing about that mistake requires invalid Markdown or malformed YAML. A syntax check can pass while the intended coverage disappears.

For this hypothetical move, the relevant edit is small:

 globs:
-  - "src/payments/**/*.ts"
+  - "packages/billing/src/**/*.ts"

Do not stop at replacing the prefix. If the new package also contains unrelated code, that replacement may widen the rule beyond its original purpose. Inspect the destination tree and choose the boundary deliberately.

Review coverage with concrete files

For a move like this, I would put three paths in the review notes:

A moved handler that should receive the rule.
A file outside billing that should not receive it.
A remaining file under the old location, if the migration is partial.

Those examples make the intended selection reviewable. During a staged migration, both locations may need coverage. After the last handler moves, remove the obsolete selector instead of accumulating paths indefinitely.

Validate those examples using the matching behavior of the consumer you actually use. Do not substitute a different glob library and assume its result proves editor behavior. Where the tool exposes loaded rules or generated configuration, inspect that evidence too. Where it does not, record that limitation rather than treating the agent's verbal assurance as a loading trace.

This is a proposed review practice, not a claim that APC ships an automatic coverage checker or that APX guarantees every editor's rule projection.

Keep narrow instructions narrow

Setting alwaysApply: true merely to make the missing guidance reappear changes the scope of the instruction. Before doing that, decide whether the guidance truly belongs on every task. A billing-specific convention usually deserves a repaired selector; a repository-wide requirement belongs in the root contract.

The practical habit is small: whenever a pull request moves a subsystem, review its rule selectors alongside imports and configuration paths. Keep the code move and its context adjustment together so a reviewer can see why both changed.

A useful rule needs accurate instructions and an accurate address. Maintaining only the prose leaves half the contract unattended.

Source project: Agent Project Context on GitHub.

Refresh APX Skills Without Replacing Your Dev Install

Manuel Bruña — Fri, 11 Sep 2026 12:02:43 +0000

You edit an APX skill, open your coding assistant, and get the old instructions again. The Markdown change is correct. The assistant may simply be reading a different file.

For contributors working from a linked APX checkout, refreshing installed skills is a separate operation from upgrading APX. Use apx skills sync when the change needs to reach the external tools' global skill directories.

Follow the file the consumer reads

Agent Project Context (APC) is the portable context layer: repository-owned instructions and definitions shared by compatible tools. APX is the daily-use runtime and tooling layer, with a local daemon, CLI, and execution surfaces.

That division also helps explain skill delivery. A project contract and a machine's installed helper files have different lifecycles. Committing an instruction does not automatically refresh every copy already installed on a developer's machine.

APX has two relevant locations inside its package:

src/core/runtime-skills/ contains instructions consumed by APX's own runtime.
skills/ supplies the separate bundled catalog distributed to external tools.

The skills documentation distinguishes these catalogs. Editing one does not imply that a consumer of the other will see the change.

A small stale-copy example

Suppose a bundled helper still describes an outdated command. You correct its source in the development checkout, then ask an external coding tool to repeat the workflow. It suggests the outdated command again.

Before rewriting the instruction, inspect the delivery path:

Confirm that your apx executable resolves to the development installation you intend to test.
Run the bundled skill refresh.
Inspect the installed helper in the target tool's global skill directory.
Verify the corrected passage is present, then exercise the workflow in the consuming tool.

The refresh command is:

apx skills sync --verbose

APX's sync handler calls the shared installer and reports results by skill and destination. Its output distinguishes created, updated, unchanged, and pruned entries. Check the destination you actually use; a successful write elsewhere does not prove your assistant read the new text.

This workflow verifies distribution first. Whether an already-open external assistant reloads its instructions is a separate question, governed by that tool. Do not treat a copied file as proof that an existing conversation has refreshed its context.

Why an upgrade is the wrong repair here

The APX contributor guide warns against using apx update to refresh a linked development checkout. An upgrade can replace the global link with a published package, leaving subsequent commands pointed at released code instead of your working tree. See the development loop.

The update implementation installs a published version through a global package manager. That is appropriate when upgrading an installed release. It is unnecessary when the intended change is a local instruction file.

The package's postinstall hook also calls the skill installer. Merely editing a development checkout does not run that hook, which explains why an explicit sync is useful.

For APX's own runtime skills, the contributor guide documents loading from the package path on demand. Diagnose that path separately; refreshing external copies cannot fix a change made in the wrong catalog.

The useful debugging question is precise: which file does this consumer read, and what operation puts the new content there? Answer it before changing the prompt again.

Project: APX on GitHub.

Grow APC Context From Real Decisions

Manuel Bruña — Thu, 10 Sep 2026 12:08:11 +0000

A directory tree in documentation is easy to mistake for a setup checklist. You see agents, skills, rules, memory, and tool configuration, then create a placeholder for everything before an agent has done any useful work.

My recommendation for APC adoption is narrower: add a context file when you can explain which recurring decision it improves. A full-looking tree is not evidence of useful context.

Separate the contract from the example

Agent Project Context (APC) is the portable context layer: repository-owned instructions and definitions that compatible tools can share. APX is the daily-use runtime and tooling layer, providing local execution through its CLI, daemon, and other surfaces.

That distinction matters during onboarding. Designing project context and configuring an execution environment are separate jobs. Installing more runtime features does not make a vague project instruction more precise.

The APC draft identifies .apc/project.json as its metadata file. Its fields describe the project name, project version, APC target version, and creation time. That metadata has a specific purpose; it is not a place to collect every setting a developer might eventually need. See the workspace metadata specification.

Likewise, the folder structure specification explicitly describes path-scoped rules as optional. A canonical location tells you where content belongs when you need it. It does not make an empty file useful.

Start with an actual mistake

Consider a hypothetical API repository where agents repeatedly edit generated client files. Before designing several specialist roles, put the relevant instruction in the root contract:

# Project Context

- Generated clients live in `src/generated/`; change the schema instead.
- Regenerate clients after schema changes.
- Run the repository's documented API compatibility checks before merge.

These instructions identify a boundary, an alternative action, and a verification requirement. They are useful even before the team has a sophisticated agent setup. In a real repository, replace the generic check reference with the command your project actually documents.

Now suppose the same schema update requires a repeatable sequence: edit the schema, regenerate clients, inspect compatibility, and update examples. That is a reason to write a reusable project skill. Its value comes from preserving the sequence that people otherwise forget.

Later, if backend-only constraints start overwhelming the root contract, a path-scoped rule has a concrete job. You are moving an existing instruction to a more precise loading boundary, with the consuming tool's support checked explicitly.

This is a proposed adoption workflow, not a claim that every tool implements every APC directory or that this article defines a formal minimum layout.

Avoid speculative context

A placeholder such as “follow best practices” gives a reviewer almost nothing to verify. A fictional release process can be worse: an agent may follow it because the repository presents it as authoritative.

For each proposed file, ask:

Which repeated question does this answer?
Who can verify that the answer is current?
What future change should trigger an update?

If those answers are missing, investigate the workflow before writing instructions for it. Empty structure can wait; incorrect guidance creates work immediately.

APX remains useful on the execution side as the project grows. Its local sessions and message history should stay in runtime-owned storage, rather than becoming filler for .apc/. The APX repository documents that storage boundary and its CLI workflow.

The practical measure is whether the next contributor or compatible agent makes fewer avoidable mistakes. Grow the context around observed needs, and review each new instruction as carefully as the code it will influence.

Project: Agent Project Context on GitHub.

A Health Check Should Identify the Runtime It Found

Manuel Bruña — Wed, 09 Sep 2026 12:05:01 +0000

A Health Check Should Identify the Runtime It Found

A green health endpoint can answer the wrong question. It may prove that a process responds on a port without proving that it is the process, configuration, or local state your client expects.

APX hit this distinction in a concrete way. One daemon could serve the normal ~/.apx home while another started with a temporary APX_HOME. Under a wildcard-versus-loopback bind, both could hold the same port, and local traffic could quietly reach the more specific listener. No obvious bind error appeared. Both daemons could still report status: ok.

The thesis: local runtime health needs a minimal identity signal, not liveness alone.

Why `ok` was misleading

An APX daemon owns machine-local state: configuration, authentication tokens, registered projects, message history, and channel connections. The port is only an address. It does not define which state directory the process serves.

Imagine this sequence:

normal daemon  -> port 7430 -> ~/.apx
test daemon    -> port 7430 -> /tmp/test-home/.apx
CLI request    -> port 7430 -> test daemon

The test daemon is technically healthy. Its database opens. Its HTTP server replies. Yet it has the wrong token store, an empty project list, and no live channels. From the client view, authentication suddenly fails and conversations disappear. A boolean health check cannot explain why.

A PID file does not solve this across homes either. If each APX_HOME owns its own PID file, the two daemons cannot see each other's lock. The collision exists at the port boundary, outside either state directory.

Add identity without exposing paths

APX now includes home_id in its unauthenticated health response. The value is a truncated SHA-256 digest of the effective APX_HOME, not the filesystem path itself.

{
  "status": "ok",
  "version": "1.92.3",
  "uptime_s": 42,
  "home_id": "<path fingerprint>"
}

Before binding, a starting daemon asks the loopback health endpoint who is already serving the port. If the returned fingerprint belongs to a different home, startup stops with a useful error. The operator can stop the other daemon or assign a separate APX_PORT.

This is deliberately narrow. The check does not publish a private absolute path. It also does not reject every listener it cannot identify. An older APX version may not return home_id, and a normal restart can briefly overlap with the outgoing process. APX fails open for those ambiguous cases, preserving restart behavior while catching the collision it can prove.

APC defines context; APX identifies execution

Agent Project Context (APC) is the portable context layer. AGENTS.md and .apc/ carry durable project instructions, agent definitions, skills, and safe shared facts across tools and machines. They should not encode one computer's daemon port or state directory.

APX is the daily-use runtime and tooling layer. It turns that portable contract into local execution through its daemon, CLI, web admin, channels, sessions, and stores. Runtime identity therefore belongs in APX health and startup checks, not in APC project files.

That separation keeps the repository portable while making local operations diagnosable. The same APC project can move between machines; each APX runtime can still prove which local home it serves.

General rule

For any local agent daemon, ask three different questions:

Liveness: did something answer?
Readiness: can it serve requests?
Identity: is it serving the state this client expects?

Collapsing all three into ok creates failures that look impossible: healthy service, broken application. A small, non-secret identity fingerprint turns that mystery into an explicit startup decision.

A2A History Should Replay Speech, Not Tool Output

Manuel Bruña — Tue, 08 Sep 2026 12:03:55 +0000

A2A History Should Replay Speech, Not Tool Output

An agent-to-agent thread has two audiences: the next agent turn needs a clean conversation, while the human operator needs evidence of what each agent actually did. Treating both audiences as one transcript creates a subtle failure mode: raw tool output starts masquerading as dialogue.

APX separates those concerns. A peer receives the messages that participants said. Tool execution remains attached to the reply as trace metadata, available for inspection without being replayed as conversation.

The thesis is simple: preserve tool traces for accountability, but do not spend conversational context on them.

How a useful thread becomes noise

Consider an APX A2A exchange:

reviewer -> opencode: Check the rendering issue.
opencode -> tool: npm run lint
opencode -> tool: a complete HTML document
opencode -> reviewer: Fixed and verified.
reviewer -> opencode: Continue with the mobile view.

If APX rebuilds history by selecting every row shared by those two participants, the next prompt may include the lint output and full HTML document as if they were earlier messages. The peer must then recover six words of intent from thousands of characters of exhaust.

This is worse than cosmetic clutter. Tool output can dominate the context window, obscure decisions, and make an agent infer that machine-generated data was something a participant intentionally said. A long-running collaboration gradually becomes less coherent even though every individual tool call succeeded.

APX therefore filters A2A history to conversational rows. Earlier requests and final replies survive. Raw tool-result rows do not enter the reconstructed dialogue.

Keep evidence, change its lane

Filtering tool output from history must not make agent work invisible. A final reply such as "fixed and verified" is only a claim unless the operator can inspect the actions behind it.

APX keeps the tool trace on the agent reply's metadata. The thread viewer can expose that trace as an action group: which tools ran, their arguments, and their results. A reply with no tool calls carries no action group. That difference helps a human distinguish completed work from an unsupported assertion.

One event now serves two views without corrupting either:

conversational text becomes future agent context;
trace metadata becomes operator evidence.

The trace remains connected to the reply that produced it, but it is not promoted into the next turn's prose.

APC and APX own different parts

Agent Project Context (APC) is the portable context layer. It stores durable project instructions, agent definitions, skills, and safe shared facts in AGENTS.md and .apc/. Those artifacts explain how agents should work across tools and machines.

APX is the daily-use runtime and tooling layer. It executes A2A turns, stores local message history, runs tools, and shapes the thread shown to an operator. Tool traces and runtime transcripts belong there because they describe machine-local execution, not portable project truth.

This boundary matters. Copying raw A2A traces into APC would turn a stable project contract into an ever-growing activity log. Dropping traces entirely would make runtime claims hard to verify. APX can retain them locally while APC stays clone-safe.

A practical rule for agent systems

When designing multi-agent history, ask what each record is for.

A user request, delegation, decision, or final answer belongs in replayable dialogue. A shell dump, file body, HTTP response, or intermediate tool envelope belongs in an execution trace. Both may need persistence, search, and a UI, but they should not automatically share a prompt budget.

This separation gives future turns better signal and gives humans better evidence. Clean context and auditability are not competing goals. They only conflict when one storage shape is forced to do both jobs.

I Stopped Testing APX in the Wrong Checkout

Manuel Bruña — Mon, 07 Sep 2026 13:03:44 +0000

I Stopped Testing APX in the Wrong Checkout

I like worktrees. They keep changes isolated, make review cleaner, and let me move fast without turning one branch into a junk drawer.

But APX made me stop trusting a worktree as a runtime witness.

That sounds like a small distinction. It is not. In APX, the daemon is the product. The CLI, the web panel, Telegram, and the other surfaces all talk to that one long-running process. And that process runs from the MAIN checkout, not from whichever worktree I happen to be editing.

That changes the meaning of "I tested it."

A green unit test in a worktree tells me the code can compile and behave in isolation. It does not tell me the running daemon loaded that code. A fresh restart tells me the daemon restarted. It still does not prove the path I changed actually executed. If I stop there, I can spend an hour convincing myself a fix is broken when the real issue is simpler: I am looking at the wrong checkout.

The trap is easy

Worktrees feel like they should be the truth because they are the place where the edit lives. In a normal app, that assumption is often good enough. In APX, it is wrong more often than I want.

The reason is structural. The daemon is long-lived. It boots once, keeps state, and serves every surface. A code change does nothing until the daemon restarts. That rule is already expensive enough. The worktree/main-checkout split makes it worse, because now I can have two versions of the repo on disk and only one of them matters to the live process.

That means I can easily do this:

Patch code in a worktree.
Run tests there.
Restart the daemon from the wrong place.
See no change.
Blame the patch.

The patch was never the problem. My mental model was.

What I check now

I keep the flow boring on purpose.

First I check which checkout the daemon is actually running from:

ps -o command= -p "$(pgrep -f 'src/host/daemon/index.js' | head -1)"

That tells me whether the live process points at the main checkout or something else. If I do not know that, I am guessing.

Then I restart from the main checkout:

apx restart

That step matters because APX keeps the JS it booted with. Restarting from the wrong directory is how I end up testing stale code while feeling productive.

Then I verify that the restart actually happened:

curl -s 127.0.0.1:7430/api/health
apx daemon logs --tail 30

The health check tells me the process is alive again. The logs tell me whether it booted cleanly and whether the pieces I care about actually came up. I do not treat either one as proof by itself.

Only after that do I exercise the real path I changed. If I touched the agent loop, I run apx exec or apx run. If I touched an API route, I hit the route. If I touched the web panel, I open the screen and click through it. The point is to make the live system answer the question, not the worktree.

Why this matters more in APX than elsewhere

APX is opinionated about where things live.

Project context belongs in .apc/.
Runtime state belongs in ~/.apx/.
The daemon owns the state that matters.
The other surfaces are clients.

That is good design, but it also means mistakes can hide in different layers at once. A worktree may contain the code I want. The daemon may still be serving older JS. The runtime state may still reflect a previous session. If I do not separate those layers in my head, I waste time debugging the wrong layer.

This is also why the repo keeps repeating the same warning in different places: the daemon runs from the main checkout, a worktree-only fix never reaches it, and a clean restart is not enough if I restarted the wrong copy. Those are not philosophical notes. They are the scars.

What changed in my day-to-day

The main change is that I stopped using worktrees as if they were runtime truth.

Now I use them for what they are good at:

isolating a branch
keeping review clean
preventing half-finished edits from bleeding into other work

But I no longer assume they are the place where verification happens.

Verification happens where the daemon lives.

That shift is small enough to miss and large enough to save time every week. It turns a vague feeling of "maybe the fix did not stick" into a concrete checklist. It also makes reviews better, because I can say exactly what I ran and what returned, instead of hand-waving about a branch that never touched the live process.

The deeper lesson

I think this is the real value of building your own runtime: it punishes vague thinking.

A spec can let you stay abstract. A runtime cannot. The runtime asks where the process starts, which checkout it sees, which files it reads live, which files it only reads at boot, and what state survives a restart. It does not care about my intent. It cares about what is actually wired up.

That sounds annoying until it saves you from a bad conclusion.

APX has made me more suspicious of any workflow that feels clever but cannot answer one blunt question: "which process is actually running this code?" If I cannot answer that, I do not know enough yet.

So I keep the workflow plain. Main checkout for the daemon. Worktrees for editing. Restart before I trust anything. Health check. Logs. Then the real path.

It is not fancy. It is just hard to fool.

And for APX, that is the point.

A Running Ollama Server Does Not Mean Your APX Model Is Healthy

Manuel Bruña — Mon, 07 Sep 2026 12:04:39 +0000

A Running Ollama Server Does Not Mean Your APX Model Is Healthy

A process can be alive while the capability you need is missing. For a local AI runtime, that distinction matters: an Ollama server answering HTTP requests does not prove that the configured model is installed.

APX treats those as separate facts. When routing a turn to an Ollama model, it checks both the server and the candidate model before accepting the route.

This is a small reliability rule with a broad lesson: health checks should test the dependency your operation actually requires, not merely the service around it.

The false-positive health check

Imagine this APX configuration:

{
  "super_agent": {
    "model": "ollama:qwen3:8b",
    "model_fallback": {
      "models": ["openrouter:openrouter/free"]
    }
  }
}

Ollama may answer GET /api/tags successfully while qwen3:8b is absent. A simple status-code check would mark Ollama healthy, select it, and delay failure until the actual model call. The router would have made a confident decision using incomplete evidence.

APX instead passes the candidate model into the provider health check. Its Ollama adapter reads the models returned by /api/tags and verifies that the requested model is available. If the server responds but the model is missing, the result is unhealthy for that route and includes the available model names for diagnosis.

The configured fallback chain can then continue naturally. No manual edit is needed just because a daemon was reachable but incomplete.

Why this belongs in APX, not APC

Agent Project Context (APC) is the portable context layer. It keeps durable project instructions, agent definitions, skills, and safe configuration hints in the repository. A project may state which model an agent should use, but it cannot guarantee that a particular machine has pulled that local model.

APX is the daily-use runtime and tooling layer. It knows the current machine, configured engines, credentials, endpoints, and locally available Ollama models. That makes APX the right place to turn a portable preference into a runtime decision.

Keeping this boundary clear prevents two bad outcomes. First, APC does not accumulate machine-specific availability state. Second, APX does not treat repository configuration as proof that an external capability exists.

Health must match the routing question

Different callers can ask different health questions. A general status screen may only need to know whether Ollama responds. A router evaluating ollama:qwen3:8b needs a stricter answer: can this provider serve this model now?

APX supports that distinction. Without a candidate model, the Ollama health probe can remain loose and report server reachability. With a candidate, it validates model presence. The router uses the strict form while walking its ordered model chain.

This avoids making every health probe unnecessarily expensive or specific, while still protecting the execution path that matters.

A practical design rule

When adding health checks to any agent runtime, write down the decision they guard.

If the decision is "show provider online," reachability may be enough.
If the decision is "send this turn to this model," verify that model.
If the decision is "run this tool," verify the tool's required dependency, not only its host process.

Also preserve diagnostic detail. "Unhealthy" is less useful than "server running; configured model not loaded." APX keeps the attempted models and reasons, so fallback behavior remains observable rather than mysterious.

Portable context gives every machine the same intent. Runtime-aware health checks let each machine execute that intent honestly.

Declare `tools` Only When Narrowing an APX Agent

Manuel Bruña — Sun, 06 Sep 2026 12:02:35 +0000

Declare `tools` Only When Narrowing an APX Agent

An agent definition should describe a durable role without freezing a temporary snapshot of the runtime around it. That is why APX treats an omitted tools field differently from a declared list.

The rule is small: omit tools when the agent should inherit APX's broad project-agent default. Declare a non-empty list only when you intentionally want a narrower allowlist.

This distinction connects the two layers. Agent Project Context (APC) is the portable context layer: the repository can carry an agent definition in .apc/agents/<slug>.md. APX is the daily-use runtime and tooling layer: it resolves that portable definition against the callable tools available on the current machine.

Omission preserves capability

Consider a project agent created without --tools:

apx agent add release-notes \
  --role Writer \
  --prompt-file ./prompts/release-notes.md

APX leaves the Tools frontmatter field undeclared. At runtime, that agent receives the broad default tool allowlist: the callable registry minus operations that belong only to the host, such as changing APX's identity, widening the permission mode, adding projects, or importing agents.

This default matters because real work crosses boundaries. A writing agent may need to read files today, call an MCP publishing tool tomorrow, and create a follow-up task next week. If creation writes today's catalog into the portable agent file, new runtime capabilities remain unavailable until someone edits the definition. The APC file becomes an accidental lockfile for APX internals.

Omission avoids that coupling. The agent keeps its stable role and instructions while APX supplies an appropriate default from the runtime it actually has.

Declaration means deliberate narrowing

Now consider a reviewer that should only inspect repository content:

apx agent add reviewer \
  --role Reviewer \
  --prompt-file ./prompts/reviewer.md \
  --tools read_file,glob

APX writes the selected tools into the agent definition. From then on, the list acts as an allowlist, not documentation or a suggestion. The reviewer does not gain run_shell, write_file, or call_mcp merely because those tools exist in the runtime.

That makes a declared list useful for agents with a genuinely constrained job:

a read-only reviewer
a documentation inspector that should not execute commands
a specialist that may call one approved MCP path but not general shell tools

The tradeoff is maintenance. A narrow list stays narrow when APX adds capabilities. That is the intended result, but only when restriction was the intent. Copying every currently available tool into the file creates maintenance cost without adding a meaningful boundary.

Capability is not prompt size

A broad allowlist sounds expensive if you imagine every tool schema entering every prompt. APX separates those concerns. The allowlist answers which tools the runtime may permit. Lightweight channels can still start with a small base set and discover additional tools when needed.

So narrowing an allowlist is a capability decision, not a prompt-budget optimization. Use it to remove powers, not to make an agent look tidy.

A practical review rule

When reviewing .apc/agents/*.md, ask why each tools list exists.

If the answer names a boundary — "this reviewer must remain read-only" — keep it. If the answer is "these were the tools available when we created the agent", remove the field and let APX resolve the default.

Also remember that runtime-specific overrides can be stricter for one execution. APX routines can replace an agent's normal allowance for a particular run, including running with no tools. That operational decision belongs in APX runtime configuration, while the APC agent file keeps the durable project-level intent.

Portable definitions work best when they state constraints that should survive across machines. Omitted tools says capability may evolve with the runtime. A declared list says this boundary must not.

DEV Community: Manuel Bruña

Give APC Rules a Useful Counterexample

Show the boundary, not just the happy path

Choose a plausible mistake

Keep examples beside the instruction

APX Community is now on Discord: build and orchestrate agents together

What you’ll find in the community

Quick start

Why I Give APX Group Conversations a Finite Budget

A mention becomes another turn

Ten replies can mean much more than ten messages

A useful stop has to stop the queue

What I would ask a room to produce

Give Temporary APC Instructions an Exit Condition

Make the condition visible

Keep the permanent rule separate

Review retirement alongside implementation

Moving a Folder? Review Your APC Rule Globs

The instruction survived; its target moved

Review coverage with concrete files

Keep narrow instructions narrow

Refresh APX Skills Without Replacing Your Dev Install

Follow the file the consumer reads

A small stale-copy example

Why an upgrade is the wrong repair here

Grow APC Context From Real Decisions

Separate the contract from the example

Start with an actual mistake

Avoid speculative context

A Health Check Should Identify the Runtime It Found

A Health Check Should Identify the Runtime It Found

Why ok was misleading

Add identity without exposing paths

APC defines context; APX identifies execution

General rule

A2A History Should Replay Speech, Not Tool Output

A2A History Should Replay Speech, Not Tool Output

How a useful thread becomes noise

Keep evidence, change its lane

APC and APX own different parts

A practical rule for agent systems

I Stopped Testing APX in the Wrong Checkout

I Stopped Testing APX in the Wrong Checkout

The trap is easy

What I check now

Why this matters more in APX than elsewhere

What changed in my day-to-day

The deeper lesson

A Running Ollama Server Does Not Mean Your APX Model Is Healthy

A Running Ollama Server Does Not Mean Your APX Model Is Healthy

The false-positive health check

Why this belongs in APX, not APC

Health must match the routing question

A practical design rule

Declare `tools` Only When Narrowing an APX Agent

Declare tools Only When Narrowing an APX Agent

Omission preserves capability

Declaration means deliberate narrowing

Capability is not prompt size

A practical review rule

Why `ok` was misleading

Declare `tools` Only When Narrowing an APX Agent