DEV Community: Manuel Bruña

Project Tasks Belong in APX, Not APC

Manuel Bruña — Tue, 14 Jul 2026 12:04:13 +0000

Project Tasks Belong in APX, Not APC

A project task is operational state.

That is why it belongs in APX, not APC.

APC is the portable context layer. It keeps the repository contract in files like AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer. It keeps the moving parts that should stay local: sessions, messages, conversations, caches, and, importantly, tasks.

That split matters because tasks feel deceptively simple. People often try to store everything in the same place: project rules, agent definitions, memory notes, TODOs, and runtime traces. The result is a blurred system where durable context and daily operations pollute each other.

APX draws a cleaner line.

In the implementation, project tasks live under:

~/.apx/projects/<project-id>/tasks/YYYY-MM.jsonl

That location says a lot.

The task log is per project, machine-local, append-only, and runtime-owned. APC does not need to version it inside the repository. The repository should define what the project is. APX should track what is happening around the project right now.

The current task store is also deliberately small. Each task is created as an event, then projected into current state. The lifecycle stays simple:

create
update
done
drop
reopen

Open tasks can also carry a workflow status such as pending, running, in_review, or blocked.

That design is practical for agent work.

If you ask APX to capture a follow-up, the CLI can write it without inventing a bigger project-management system:

apx task add "Review auth edge case" --tag bug --agent reviewer --due 2026-07-15
apx task list --state open
apx task done t_ab12cd

Those commands are useful precisely because they stay local to APX runtime state. They do not rewrite your repository contract. They do not pretend a temporary follow-up note is the same kind of artifact as AGENTS.md, .apc/project.json, or .apc/mcps.json.

There is also a structural reason this belongs in APX.

Tasks are tied to runtime activity. APX exposes per-project task APIs, a global task view across registered projects, task summaries for status screens, and task-aware tools for the super-agent. That is operational plumbing, not portable specification. APC-compatible tools may understand agent definitions or project metadata, but they should not be forced to inherit one runtime's transient TODO stream.

This is the same boundary APC and APX keep elsewhere.

APC stores durable, reviewable project intent.
APX stores live execution state.

A task like "re-run migration after vendor update" is real work, but it is not project contract. It may matter only on one machine, for one agent, during one week. Storing it in APX keeps the repo clean while still making the work visible and queryable.

The alternative looks worse in both directions.

If tasks go into APC, the repository starts collecting operational noise that should not travel forever. If tasks stay only inside ad hoc chat threads, they become hidden, vendor-tied, and hard to inspect later.

APX avoids both problems by giving tasks a first-class local store.

That also makes the APC/APX relationship easier to explain:

APC tells a runtime what this project means.

APX tracks what this project is doing.

For daily agent work, that is the right split. Keep the shared contract in APC. Keep the changing task flow in APX.

I Stopped Treating the Web Admin as a Separate Product

Manuel Bruña — Mon, 13 Jul 2026 13:05:09 +0000

I Stopped Treating the Web Admin as a Separate Product

I used to think the browser UI was the polished layer and the CLI was the serious layer.

That split felt natural for a while. The CLI was where I trusted the work. The web view was where I expected convenience, maybe better visibility, maybe a nicer way to poke around when the terminal got crowded. But while building APX, that mental model kept producing one annoying symptom: drift.

The browser could show something useful, but if it did anything more than mirror the same state and actions as the daemon, it started to become its own little product. Then the CLI and the web panel slowly stopped agreeing on what mattered, or how to name it, or which path owned the truth.

That is the part I finally stopped tolerating.

My current thesis is simple: the APX web admin only works when it stays a thin surface over the same daemon, the same repo-owned project state, and the same local runtime rules. If the browser invents a second version of the system, the convenience is fake. If it reads and writes the same core state, it becomes genuinely useful.

What APX actually is

The APX README says the system in plain words: APX is a daemon plus CLI. The daemon is a local HTTP server that manages projects, agents, sessions, and message logs. The web admin is a browser UI served by that daemon. It is not a separate backend. It is the same runtime seen through another surface.

That distinction matters more than it sounds.

If the browser talks to a different store, or keeps its own state, or re-implements a business rule just to feel faster, then I am no longer using one system. I am using two systems that happen to share a logo.

APX is opinionated about storage for the same reason. The repo owns project definitions and curated memory. Runtime noise lives under ~/.apx/ and stays local. That split already tells me where the web UI should stand. It should render the same project contract, not create a separate one.

Where the drift showed up

I started noticing the problem in small ways.

A task would look right in the browser, but the command-line flow would still expose the older shape.

A project setting would be easy to edit in one place, but the other surface would lag behind or use a slightly different name.

A session history view would be handy, but the action behind it would not map cleanly to the same daemon call the CLI used.

None of those bugs were dramatic by themselves. The real damage was cumulative. Every time I let one surface improvise, I created another place where I had to remember what the system was supposed to mean.

That is a bad trade.

I do not want my own tooling to depend on me carrying parallel mental models. I want one model, many views.

The browser is good at browsing

The browser is still valuable. I am not arguing against it. I am arguing for a narrower job.

A browser is good at:

scanning lots of state quickly
comparing several things side by side
editing structured data without leaving the machine
showing relationships that are annoying in a terminal
making the daemon feel inspectable instead of hidden

That is already enough.

In APX, the web admin covers the right kind of surfaces for that job: projects, chat, tasks, routines, MCPs, memories, skills, docs, files, and the rest of the local control plane. The browser should help me see what is going on, not redefine what is going on.

That is why I like the docs phrase that the web admin is the same runtime in the browser. That is the right mental frame. Same runtime, different interface. Not same brand, different truth.

What I changed in practice

Once I accepted that, the implementation discipline got simpler.

The daemon became the place where the real work lives. The web panel became a client of the daemon. The CLI stayed a second client of the same daemon. Both surfaces can be opinionated about presentation. Neither surface should own the domain rules on its own.

That gives me a clean test for every feature:

If the behavior matters to the product, it belongs in the daemon or core.
If the behavior is only about how a surface presents that state, it belongs in the surface.
If a feature cannot be expressed cleanly in both CLI and web, the design is probably too surface-specific.

That test has saved me from building UI-only logic that felt nice in the moment and then turned into maintenance debt later.

The other thing that changed is how I think about authentication and locality. The web panel runs on 127.0.0.1:7430 and uses the daemon over HTTP. It does not need a public server to feel modern. If I want another device on the same LAN to join, APX has an explicit pairing path. That is a better shape than quietly opening the door and hoping nobody notices.

Local-first is not a marketing slogan here. It is what keeps the browser honest.

The real lesson

The web admin taught me something that the CLI alone did not make obvious.

A tool can feel unified from the terminal and still be split in practice if the surfaces each accumulate their own ideas.

That is the trap I keep watching for now. The browser UI is tempting because it is easy to add just one more convenience: a cached view, a special action, a shortcut that skips the core path. Each one looks harmless. Together they turn one system into a fork.

So I am trying to stay strict about the boundary.

APC holds the project contract in the repo.

APX owns the local runtime, daemon, and local state.

The web admin is only a view over that same runtime.

When I keep those layers separate, the whole thing gets easier to understand, easier to debug, and easier to trust. When I blur them, I spend more time explaining my own tool than using it.

That is why I stopped treating the web admin as a separate product.

It is not a second product. It is a second angle on the same machine.

Source notes

The concrete pieces behind this are already in the repo and docs:

APX README: daemon + CLI, browser UI, and local state split.
APX docs on the daemon: every surface talks to the same host layer.
APX docs on the web panel: browser UI over HTTP, no public server by default.
APX docs on projects and memory: repo-owned project context, local runtime state.

That is the boundary I want to keep. The browser can be friendly. It does not need to become independent.

Project Config Should Travel With APC

Manuel Bruña — Mon, 13 Jul 2026 12:02:35 +0000

Project Config Should Travel With APC

When a team decides how an agent should behave in one repository, that decision should travel with the repository.

That is why project config should live in APC.

APC is the portable context layer. It keeps repository-owned agent context in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer. It reads that portable context, merges it with machine-local runtime settings, and keeps sessions, messages, and secrets outside the repo.

That split becomes especially useful with configuration.

APX documents two config layers.

Global config lives in ~/.apx/config.json.
Project config lives in .apc/config.json.

The rule is simple: machine-local settings stay machine-local, but repo-owned behavior travels with the project.

This is stronger than convenience. It is a boundary that prevents silent drift.

Imagine a team wants one project to route Telegram messages to a reviewer agent and to use a different super-agent model than the default machine setting. If that choice lives only in one developer's ~/.apx/config.json, the behavior is no longer really part of the project. Another clone on another machine can register the same APC project and get different operational behavior without noticing.

Putting that override in .apc/config.json fixes the problem.

A small example from the APX docs looks like this:

{
  "super_agent": {
    "model": "groq:llama-3.3-70b-versatile",
    "permission_mode": "total"
  },
  "telegram": {
    "route_to_agent": "reviewer"
  }
}

That file belongs in the repo because it expresses project intent. APX then applies it only for that project.

The CLI makes the workflow explicit:

apx project config set my-app super_agent.model groq:llama-3.3-70b-versatile
apx project config set my-app telegram.route_to_agent reviewer
apx project config show my-app --effective

This is the right division of labor.

APC owns the durable contract. APX owns the runtime merge.

The same docs also draw the line that matters most: never put secrets in .apc/config.json. API keys, provider credentials, daemon settings for your machine, and other private runtime details belong in ~/.apx/config.json, not in the repository. APC should carry safe, reviewable project behavior. APX should keep private operational state local.

That gives teams a clean model:

commit project overrides
keep credentials local
let APX merge both at runtime

Without this split, teams usually fall into one of two bad patterns.

The first bad pattern is hiding project behavior in one laptop. The project becomes harder to reproduce because important agent settings are no longer visible in code review.

The second bad pattern is committing too much. People start placing keys, local provider endpoints, or one-off machine tweaks into shared files because there is no clear boundary between project config and runtime config.

APC and APX avoid both mistakes by naming the boundary directly.

There is also a portability advantage here. APC does not need to know how APX stores sessions, messages, or caches. It only needs to preserve the project-owned facts another runtime could understand later. A committed .apc/config.json is part of that project contract. Even if another APC-compatible runtime eventually reads only part of it, the repository still has a visible, reviewable source of truth for its intended behavior.

So the practical thesis is small but important:

If a setting describes how this repository should behave, put it in APC.

If a setting describes your machine, your credentials, or your local runtime state, keep it in APX.

Portable context should travel. Private runtime state should not. Project config is one of the clearest places where that APC/APX boundary pays off every day.

Skill Bodies Should Load on Demand

Manuel Bruña — Sun, 12 Jul 2026 12:02:53 +0000

Skill Bodies Should Load on Demand

A good skill system has two jobs that pull in opposite directions.

First, the project needs durable instructions that live in version control. That is APC's job. A project can keep reusable skill files under .apc/skills/, and agents can reference those skills by name from AGENTS.md or .apc/agents/<slug>.md.

Second, the runtime needs to stay fast and focused during actual work. That is APX's job. If every skill body is injected into every turn, the prompt gets noisy, token costs rise, and the model starts seeing instructions that do not matter for the current request.

That is why APX is right to treat skill bodies as on-demand runtime material rather than permanent prompt baggage.

In APC, the skill file is the project-owned source. The spec keeps this simple: skills are reusable instruction files under .apc/skills/<name>.md, meant to avoid repeating the same operational guidance across many agents. That keeps the durable contract in the repo, reviewable like any other project artifact.

But APX does not have to dump that whole contract into the model on every turn.

The runtime code is explicit about this tradeoff. In src/core/agent/skills/catalog.js, APX builds a compact skills hint block that lists only slugs. It tells the model that bodies are not loaded, that it can call list_skills to browse one-line descriptions, and load_skill({slug}) to fetch the full body when exact syntax is needed. That is a better default than preloading everything.

Why? Because most turns do not need most skills.

If a user asks for a quick summary, a design opinion, or a small code fix, loading a release checklist, a deployment runbook, a security review guide, and a migration playbook all at once just burns attention. The model now has to separate relevant instructions from irrelevant ones before it can even start solving the task.

APX also keeps the loading order practical. In src/core/agent/skills/loader.js, project skills shadow global ones, and global skills shadow built-in runtime skills. So APC keeps ownership of project-specific behavior, while APX still provides a safe fallback catalog. That split matters: portable context stays in the repo, but runtime convenience does not get mistaken for project truth.

There is an even stronger version of the same idea in APX's optional Skill Inspector. When enabled, the runtime suppresses the static slug dump and re-evaluates the current prompt each turn. High-confidence matches can inline one skill body. Lower-confidence matches become hints. Everything else stays out. The point is not magic retrieval. The point is prompt discipline.

This is the deeper APC/APX boundary:

APC should preserve reusable knowledge.
APX should decide how much of that knowledge becomes active for this turn.

A concrete example makes the split clearer.

Imagine a repo with these skills:

release-checklist
security-review
support-triage
docs-style

Those files belong in .apc/skills/ because they are durable project instructions. But if the user asks, "Explain this error log and suggest the smallest patch," APX should not inject all four bodies. A small hint that those skills exist is enough. Only if the turn becomes a release task or a security audit should the runtime pay to load the matching body.

That behavior keeps APC portable and APX usable.

Portable context is not the same as always-active context. A project can own many valid instructions without forcing every runtime turn to carry all of them. Once you accept that distinction, the architecture gets cleaner: APC stores the skill files, APX routes them into the prompt only when the request actually needs them.

That is the right default for daily agent work.

Path-Scoped Rules Belong in APC

Manuel Bruña — Sat, 11 Jul 2026 12:05:45 +0000

Path-Scoped Rules Belong in APC

A repository should not need different hidden rule copies for different tools.

That is why path-scoped rules belong in APC.

APC is the portable context layer. It keeps repository-owned meaning in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer. It helps current agents and runtimes work with that portable context while still keeping sessions, messages, and other runtime state outside the repo.

The split matters most when one rule should apply only to one part of the codebase.

One repo, different rule zones

Most projects do not have one flat instruction surface.

Frontend code may need accessibility checks and bundle-size discipline. Backend code may need input validation at the route boundary. Support content may need a specific tone and escalation path. If all of that lives only in one giant root prompt, agents either ignore the details or carry too much irrelevant guidance into every task.

APC gives a cleaner shape:

AGENTS.md for repository-wide rules
.apc/rules/ for reusable or path-scoped rules

The APC rules spec is explicit about this. AGENTS.md is the broad root contract. .apc/rules/ is where rules can become smaller and more targeted.

A recommended file can look like this:

---
description: "Backend API rules"
globs:
  - "src/api/**/*.ts"
alwaysApply: false
---

- Validate request input at the route boundary.
- Keep database writes inside service functions.

That is a better boundary than copying the same instructions into Cursor rules, Claude-specific files, and a runtime-local note that no one reviews.

Why APC should own these rules

Path-scoped rules are still project meaning.

They describe how this repository wants work done in these paths. That is exactly the kind of information that should survive a fresh clone, code review, and a runtime change. If the rules live only in one editor's private directory, they stop being part of the project contract and start being workstation trivia.

APC fixes that by keeping the source in .apc/rules/.

The folder structure docs make the intent clear: path-scoped .mdc rules are project-owned, safe to commit, and distinct from runtime state. Sessions, conversations, messages, caches, and private memory do not belong there. APX keeps those under ~/.apx/ instead.

That separation keeps two different concerns from bleeding together:

APC stores durable guidance worth reviewing.
APX stores local operational history worth keeping out of git.

Why this also helps APX

APX works best when the repository already has a clean contract.

The APC reference docs describe APX as the runtime bridge that makes .apc/ usable today. It handles the daemon, CLI, runtimes, engines, and local storage. It should not become a second source of truth for project rules.

If path-scoped guidance already lives in APC, APX can stay thin. It can help compatible runtimes use the repo context without owning a second project-specific rules database.

That is also future-proof. The APC rules docs explicitly allow compatible consumers to project .apc/rules/*.mdc into tool-specific rule systems when needed. The important part is not the projection target. The important part is the source stays in the repo.

Practical example

Suppose a monorepo has these needs:

AGENTS.md: run tests before merge, never commit secrets, keep migrations reversible
.apc/rules/frontend.mdc: preserve keyboard navigation and avoid text-only icon buttons
.apc/rules/backend.mdc: validate input at the boundary and keep writes inside services

Now the project can move across tools without rewriting its own discipline each time.

APC keeps the rule map portable. APX keeps the runtime local. That is the right division of labor.

Bottom line

Path-scoped rules belong in APC because they are part of the repository contract, not part of one runtime's private memory.

Keep broad rules in AGENTS.md. Keep narrower, reusable, path-aware rules in .apc/rules/. Let APX handle execution, sessions, and local tooling around that contract instead of duplicating it.

Project Skills Should Override Global Skills

Manuel Bruña — Fri, 10 Jul 2026 12:04:48 +0000

Project Skills Should Override Global Skills

When an agent needs operational instructions, the worst outcome is ambiguous precedence. A project wants one behavior, your machine has another, and the runtime quietly picks the wrong one.

APC and APX avoid that by making skill scope explicit.

APC is the portable context layer. It keeps project-owned instructions in the repository, including .apc/skills/. APX is the daily-use runtime and tooling layer. It discovers those skills, lets the super-agent load them on demand, and still keeps a machine-wide skill catalog under ~/.apx/skills/ plus its own built-in runtime skills.

The important rule is simple: project skills win.

Three skill lanes, one precedence order

The APX skills docs and loader code define one runtime catalog with three sources, in this order:

<project>/.apc/skills/<slug>/SKILL.md or <slug>.md
~/.apx/skills/<slug>/SKILL.md
APX built-in runtime skills under src/core/runtime-skills/

The first matching slug wins. That means a project skill can override a user-global skill, and a user-global skill can override a built-in one.

That is the right order because APC owns project meaning.

If a repository says its deploy-checklist skill should work a certain way, that project-local instruction should beat whatever happens to be installed globally on one laptop. Otherwise the same APC project would behave differently depending on whose machine ran it.

Why APC needs the top slot

Portable context only works if the repository can carry its own exceptions.

Imagine you keep a global release-notes skill in ~/.apx/skills/ that fits most projects. Then one repository has stricter rules: mention migration risk, list MCP changes separately, and never claim a release is safe without test output.

That repository should not need a forked runtime or a custom machine setup. It should only need:

.apc/skills/release-notes/SKILL.md

Now APX reads the project skill first, and the super-agent loads the correct instructions for that repository.

That is APC doing its job: project-specific context travels with the repo.

Why global skills still matter

Global skills are still useful. They are the machine-wide layer for habits you want everywhere on one workstation.

Examples:

personal writing style
preferred debugging checklist
local publishing workflow
a custom skill for a tool only you use

APX stores those in ~/.apx/skills/, so they stay available across projects on that machine without polluting any repository.

That is also the APC/APX split in miniature:

APC keeps shared, reviewable, repo-owned instructions.
APX keeps operator-local runtime customizations.

A global skill should be convenient. It should not outrank a project contract.

Why built-in skills stay as the safety net

APX keeps a third lane for built-in runtime skills. The docs describe those as private: always available, always active, and not deletable from scope settings.

That matters because APX ships its own operational knowledge there: apx-* skills, apc-context, and runtime-specific guidance. If users could accidentally delete or fully disable that foundation, the runtime would lose basic self-knowledge about how to use its own commands and structures.

So the full design is not just “project overrides global.” It is:

project wins when the repo needs a local rule
global wins when the operator wants a machine-wide customization
built-in remains as the fallback safety net

On-demand loading keeps prompt cost low

This precedence model works well because APX does not dump full skill bodies into every prompt.

The runtime exposes list_skills and load_skill, and APX documents that load_skill pulls the full body only for the current turn. The baseline prompt stays small, while exact instructions stay available when needed.

That means you can keep project-specific skill overrides in APC without paying for all of them on every message.

Practical rule

Use each lane for its real job.

Put repo-owned exceptions in .apc/skills/.
Put personal machine-wide helpers in ~/.apx/skills/.
Leave built-in APX runtime skills alone unless you are intentionally shadowing them with a better local or project version.

If one slug means different things in two repositories, that is not a bug. That is exactly why the project lane exists.

Bottom line

Project skills should override global skills because APC owns portable project intent.

APX makes that practical with a clear precedence chain, built-in fallback skills, and turn-local skill loading. The result is predictable behavior: the repo decides project meaning, the machine adds personal convenience, and the runtime still keeps its own minimum operational floor.

You're not 'a programmer' anymore. You're one of these 5 archetypes.

Manuel Bruña — Thu, 09 Jul 2026 22:26:49 +0000

Boris Cherny — the creator of Claude Code at Anthropic — shared an idea that stuck with me all day: in the AI era, we've stopped being "the person who writes code" and started moving between 5 developer archetypes.

They're not job titles or seniority levels. They're ways of working — and most of us move through all of them depending on where a project is.

Here's the breakdown, plus why I think it's one of the most useful lenses I've found for reading my own work. 👇

The 5 archetypes

🧪 1. Prototyper — the spark

The zero-to-one person. Fires off ideas and experiments, most of which never ship — and that's the point. Their job isn't to be right; it's to find out fast whether something is worth building at all. They don't fall in love with the code, they fall in love with learning.

"It doesn't work yet, but look at what's coming."

🏗️ 2. Builder — makes it real

Takes that duct-tape prototype and turns it into an actual product: real features, real infrastructure, something that holds up when real users show up. From "cool demo" to "this survives production."

"Give me the chaos and I'll hand you something that works."

🧹 3. Sweeper — the one who subtracts

Simplifies the code and the system. Deletes what's unnecessary, cleans up the UI, kills bugs, pays down technical debt. Their superpower is removing, not adding — the quiet work that keeps everything else from collapsing.

"Less code, less debt, more speed."

📈 4. Grower — pushes toward product-market fit

Takes a built product and iterates it, again and again, toward the thing people actually want. Lives on metrics, feedback and experiments.

"It works. Now let's make them actually want it."

🛠️ 5. Maintainer — the silent hero

Owns the mature system. Keeps it secure, reliable and fast while it scales. The person who prevents the fires you never hear about.

"If you didn't notice it went down, that was me."

The detail almost nobody sees

Here's what I loved most: these aren't your job title.

On the Claude Code team, everyone shares the same title. A designer can be a Prototyper. A PM can be a Maintainer. It's how you work, not what your contract says.

And each stage of a product asks for a different mix:

Pre-PMF: Prototyper + Builder + Sweeper
Growth: Builder + Sweeper + Grower
Maturity: Sweeper + Grower + Maintainer

The AI doesn't erase these roles — it makes them sharper. When an agent can knock out the mechanical parts, what's left is the judgment call about which mode the moment needs.

So… which one are you?

The honest answer for most of us is: it changes. You shift archetype depending on the project, the week, sometimes the hour. I'm a Builder at heart, but lately I've been living in Sweeper mode. 😅

Which of the 5 do you feel most like in your day-to-day? I'd genuinely love to read it in the comments. 👇

Inspired by an idea from Boris Cherny, creator of Claude Code.

A Stable Project ID Keeps APC Portable and APX Local

Manuel Bruña — Thu, 09 Jul 2026 12:04:01 +0000

A Stable Project ID Keeps APC Portable and APX Local

A lot of agent tooling problems start with a bad identity model. If a runtime treats a folder path as the project identity, everything looks fine until you rename the repo, move it to another machine, or register the same code from a different checkout.

APC and APX avoid that trap by splitting identity from runtime state.

APC is the portable context layer. It keeps the committed project contract in the repository. APX is the daily-use runtime and tooling layer. It reads that contract, then keeps sessions, messages, caches, and other machine-local state outside the repo.

A small file is what makes that split work: .apc/project.json.

`project.json` gives the project a durable identity

The APC docs define .apc/project.json as the canonical metadata file for a project. Its job is intentionally boring: say what the project is called, which APC version it targets, and when that metadata set was created.

A minimal APC shape looks like this:

{
  "name": "My Project",
  "version": "0.1.0",
  "apc": "0.1.0",
  "created": "2026-05-08T00:00:00Z"
}

APX extends that practical story with one more field when it initializes a real working project:

{
  "name": "my-app",
  "version": "0.1.0",
  "apf": "0.1.0",
  "created": "2026-01-15T10:00:00Z",
  "apx_id": "077078af9dd7"
}

That apx_id is the key detail. APX documents it as the stable identifier that links the committed APC definition to local runtime state under ~/.apx/projects/<apx_id>/.

So folder path is not the identity. Repo display name is not enough either. The stable id is the bridge.

Why that matters in daily work

Imagine this sequence:

You run apx init in a repository.
APX creates .apc/project.json and generates apx_id once.
You register the project with APX.
APX stores runtime state under ~/.apx/projects/<apx_id>/.

Now later you:

rename the repo directory
move it to another path
clone it on another machine
reopen it from a different tool

The APC contract still travels with the repo, because it lives in AGENTS.md and .apc/. The APX runtime state still has a clear local home, because it hangs off the stable id, not off an unstable folder name.

That is exactly the APC/APX division in practice:

APC says what project this is.
APX says what happened while this machine worked on it.

Without a stable id, a runtime has to guess. It may create duplicate local projects, lose message history after a rename, or tie private runtime state too tightly to one filesystem path.

Portable definition, local runtime

The APX project docs make the storage split explicit:

<repo>/.apc/ holds agent definitions, skills, MCP hints, and project config.
~/.apx/projects/<id>/ holds sessions, conversations, messages, caches, task logs, and other runtime files.

That design has two benefits.

First, the repository stays reviewable and clone-safe. APC contains portable context, not machine junk.

Second, APX stays honest about privacy and locality. Runtime transcripts, caches, and logs do not quietly end up in git just because a tool needed somewhere convenient to put them.

One practical rule

Treat .apc/project.json like identity, not like a scratchpad.

Do not turn it into a dump of runtime flags, private state, or session metadata. The APC spec keeps it small for a reason. The more stable it stays, the more reliable the bridge to APX becomes.

Likewise, do not change apx_id casually. APX documents that field as the permanent key for the local runtime folder. If you break that link, APX will not know that old local state belongs to the same committed project. If you move the repo, the APX docs point to apx project rebuild as the right repair step.

Bottom line

Portable context needs a stable identity, not a lucky pathname.

APC provides the committed project contract. APX provides the local runtime layer. .apc/project.json is the small boundary object that lets both sides do their job without leaking into each other.

That is not glamorous design. It is better: it keeps project meaning portable and runtime state local.

Agent Slugs Are the Smallest Handoff Key Between APC and APX

Manuel Bruña — Wed, 08 Jul 2026 12:03:00 +0000

Agent Slugs Are the Smallest Handoff Key Between APC and APX

A lot of APC and APX discussion happens at the level of folders, memory, or runtimes. But there is a smaller boundary that matters every day: the agent slug.

APC is the portable context layer. It keeps the project contract in the repository: AGENTS.md, .apc/project.json, .apc/agents/<slug>.md, skills, commands, and curated memory that is safe to share. APX is the daily-use runtime and tooling layer. It reads that contract, runs agents, stores local runtime state under ~/.apx/, and gives you CLI, daemon, and web admin workflows.

The slug is where those two layers meet.

In APC, the slug identifies the structured agent definition. In APX, the same slug becomes the routing key for commands like apx run <slug>, apx exec -a <slug>, apx memory <slug>, and apx session new <slug>. APX also uses it to place runtime files under per-agent paths such as ~/.apx/projects/<project-id>/agents/<slug>/sessions.

That sounds small, but it solves a real design problem: how do you keep a portable project contract and a local runtime aligned without inventing hidden IDs for every agent?

The answer is not to make the runtime smarter. The answer is to keep the join key boring.

Why this matters

If the shared name for an agent is unstable, everything around it gets noisy.

Session history stops feeling continuous.
Runtime memory becomes harder to inspect.
Telegram routing, CLI commands, and follow-up sessions become less predictable.
Teams start treating agent definitions like disposable prompts instead of durable project roles.

A stable slug avoids that.

For example, if a repository defines .apc/agents/reviewer.md, APX can keep using reviewer everywhere:

apx run reviewer --runtime claude-code "Review the open PRs"
apx exec -a reviewer "Summarize test risk"
apx memory reviewer
apx session new reviewer --title "Follow-up audit"

That is a better contract than a display name. You can rename a role description, change the model, or expand the skills list, and the runtime history still lands under the same agent lane.

What should stay stable

The slug should describe the durable responsibility, not the mood of the prompt.

Good slugs:

reviewer
planner
backend
release-manager

Weak slugs:

smart-reviewer-v2
best-agent-final
claude-helper
telegram-reviewer-temporary

Those weaker names leak implementation details into the project contract. They age badly when you switch models, channels, or runtimes. APC should describe the project role. APX should decide how that role runs today.

APC side, APX side

APC keeps the definition portable:

AGENTS.md holds repository-wide rules.
.apc/agents/<slug>.md holds the structured agent definition.
.apc/agents/<slug>/memory.md can hold curated, team-safe memory.

APX keeps the runtime local:

sessions
conversations
message logs
runtime memory and caches

That split only stays clean if both sides can point to the same agent identity without translation glue. The slug is enough.

This is also why APX does not need a second hidden naming system for normal agent work. The portable name from APC already gives the runtime a stable filesystem lane, command target, and audit trail anchor.

Practical rule

Pick slugs like you would pick API names.

Stable over clever
Role-based over model-based
Short over decorative
Reusable over temporary

If you need to change how an agent behaves, edit the definition. If you need a different responsibility, create another slug.

That keeps APC readable in the repo and APX readable on disk.

The bigger APC/APX idea is often described as portable context plus local runtime. That is true. But in daily use, the smallest piece doing real work is often just one good slug.

Not Every Memory Belongs in APC

Manuel Bruña — Tue, 07 Jul 2026 12:03:53 +0000

Not Every Memory Belongs in APC

A lot of agent setups fail for the same reason: they treat all memory as one bucket.

That is not what APC and APX are trying to do.

APC is the portable context layer. It should keep only durable project facts that are safe to share, review, and commit.
APX is the daily runtime layer. It should keep local agent memory, cross-channel recall, sessions, and other runtime state outside the repo.

That split matters because different kinds of memory solve different problems.

If you put everything into APC, the repo fills with private notes, temporary conclusions, and stale conversation debris.
If you keep everything in APX, the project loses durable knowledge every time a machine, runtime, or session changes.

The better model is simple: APC stores what the project should remember. APX stores what the runtime needs in order to work.

APC memory: portable, curated, team-safe

In APC, curated memory lives with the project under:

.apc/agents/<slug>/memory.md

That file is for durable facts tied to the agent's project role. Good examples are:

long-lived constraints
team conventions
architectural decisions
recurring responsibilities
stable domain facts

This kind of memory is boring in the best way. It is plain Markdown, easy to diff, easy to review, and easy to migrate to another tool.

A reviewer agent might keep something like this:

# Memory - reviewer

## Project facts
- Prefer findings-first reviews.
- API compatibility matters more than internal file layout during v0.1.

## Durable decisions
- Use pnpm, never npm.

That belongs in APC because another contributor, another IDE, or another runtime should be able to read the same project rule later.

APX memory: local, operational, runtime-owned

APX has a different job. It is the runtime and tooling layer, so it keeps machine-local memory where the repo should not.

Per-agent runtime memory lives under:

~/.apx/projects/<project-id>/agents/<slug>/memory.md

That file is injected into the agent prompt on every call. It is useful for local operational context, owner preferences, and durable notes that help the runtime, but should not automatically travel with the repository.

APX also has a separate cross-channel memory system:

~/.apx/memory.md
~/.apx/memory.db

That layer powers automatic recall across channels. It can remember recent facts, retrieve semantically relevant past messages, and compact long histories without turning the repo into a session dump.

So APX already tells us something important: not all memory should be committed, and not all memory should be global.

Practical rule: decide by visibility, not by format

The mistake teams make is judging memory by file type instead of visibility.
A memory.md file can still be the wrong place if the content is private, temporary, or unreviewed.

A better rule is:

Put it in APC if the whole project may need it later and it is safe to commit.
Keep it in APX if it is runtime-local, personal, temporary, or derived from ongoing sessions.
Leave it out of both if it is raw noise.

For example:

"Use pnpm, never npm" belongs in APC.
"Owner prefers short PR summaries" may belong in APX runtime memory.
"This session explored three bad refactors before finding the safe path" belongs in session history, not in either memory file.

That last example is the real trap. Raw transcripts feel informative, but they age badly. Future contributors do not need every thought. They need the final durable fact, constraint, or decision.

Why APC and APX fit together here

This is where the APC/APX split becomes useful instead of abstract.

APC gives the project one portable place for curated meaning.
APX gives daily work a local runtime that can keep richer state without leaking it into the repo.

That means you can switch tools, machines, or runtimes without losing the project contract, while still letting the runtime keep the messy memory it needs.

The clean workflow is:

Work in APX.
Let sessions, recall, and runtime memory stay local.
Extract only durable, sanitized facts into APC.

Not every memory deserves version control.
But every durable project fact should have a portable home.

APX Works Best When the Bridge Stays Thin

Manuel Bruña — Mon, 06 Jul 2026 13:03:33 +0000

APX Works Best When the Bridge Stays Thin

I kept trying to make APX do more than it should.

That is the honest version.

At first I wanted APX to feel like a single control surface for everything: project rules, runtime choice, agent identity, session history, message logs, and whatever else a tool might need to feel "smart". The problem was not that the features were wrong. The problem was that I kept asking the bridge to become the house.

That is where the work got messy.

The part that finally clicked for me is simple: APX works best when the bridge stays thin. APC should hold the project contract. APX should handle the moving parts. If the runtime starts carrying project meaning that should live in the repo, or if the repo starts carrying machine-specific behavior, the boundary blurs and the system becomes harder to trust.

That sounds abstract until you look at the actual code.

What the bridge really does

In APX, the bridge is not a giant translation layer. It is a small set of decisions that let a runtime do useful work without pretending to own the project.

The README already says the split plainly: APX is a daemon plus CLI, it manages projects, agents, sessions, and logs, and the local state lives under ~/.apx/. That part matters because it tells you what APX is for: live work, not durable project meaning.

The runtime bridge tests pushed me toward the same conclusion. buildApfHint() is intentionally slim. It substitutes the placeholders the runtime needs, and nothing more. The test even guards against leftover template markers. That sounds minor, but it is the right instinct: the hint should be enough for the runtime to know where it is, not a second copy of the entire APC story.

That is the boundary I want everywhere in APX.

Identity is not the same as context

Another thing I had to stop mixing up: identity and project context are related, but they are not the same problem.

buildIdentityBlock() injects the agent name, personality, owner, owner context, and language into the super-agent prompt. The tests make that explicit. If identity is missing, the prompt becomes vague. If language is wrong, the whole experience feels off even when the logic is correct.

So APX needs to be opinionated about identity.

But it still should not become the source of truth for the project itself.

Identity is runtime behavior. It tells the agent how to speak, who owns it, and which language to use. APC is still where the project rules live. That separation is what keeps the tool from drifting into a pile of hidden defaults.

I used to think more data in the prompt would solve this. It does not. It just creates a bigger prompt with more chances to go stale. A thinner bridge with explicit identity is easier to debug than a fat prompt that tries to impersonate the whole repo.

Setup is not initialization

The distinction between apx init and apx setup is one of the cleanest examples of the split.

apx init is project work. It scaffolds APC into a repo and points you at the durable files.

apx setup is machine work. It is the interactive first-run wizard that asks about provider, model, channels, and language. It also starts the daemon and wires in the local runtime choices that do not belong in a repo.

That separation helped me stop asking one command to do two jobs.

If I blur them, I end up with a setup flow that leaks machine preference into the project. If I keep them separate, the repo stays portable and the machine stays configurable. The user sees a cleaner model: project first, runtime second.

That split also makes failure easier to reason about. If a project is wrong, I fix APC. If a machine is wrong, I fix APX. I do not have to guess whether the bug is in a repo artifact or in the local daemon state.

What changed for me

The biggest practical change was not a new feature. It was a new discipline.

I stopped trying to make every layer remember everything.

Now I want each layer to remember only what it owns:

APC remembers the project contract
APX remembers runtime state, sessions, and machine-local behavior
identity is injected when the runtime needs to speak
logs and session metadata stay local, where they can be inspected without polluting the repo

That shift matters because the system became easier to debug.

When a session goes wrong, I no longer wonder whether the agent lost the project rules or whether the runtime picked a weird local state. I can look at the boundary. I can inspect the APX session frontmatter, the runtime bridge, or the APC files in the repo and see which side is responsible.

That is the real benefit of a thin bridge: less mystery, less duplication, fewer places for truth to split.

Why I still like the split

I still think APX is the right place for the messy parts.

It bridges Claude Code, Codex, OpenCode, and Aider. It handles local sessions. It owns the daemon. It keeps the runtime state where it belongs. That is a lot of responsibility, but it is the right kind of responsibility because it is machine-shaped.

APC stays simpler because of that. It does not have to know how every runtime behaves. It just has to describe the project clearly enough that any compatible tool can enter the repo and understand what it is looking at.

That is the part I care about most now: APC should be portable, APX should be local, and the bridge between them should stay narrow enough to trust.

If I get greedy and push more meaning into APX, I usually regret it later. If I keep the bridge thin, the whole stack becomes easier to maintain, easier to explain, and easier to reuse the next time I need another tool to join the project.

That is the rule I am keeping.

And it is the one that finally made APX feel like a runtime instead of a second copy of the project.

Source notes

The concrete parts behind this lesson are already in the repo:

APX README: daemon + CLI, local state under ~/.apx/, runtimes, engines, and plugins.
runtime-bridge.test.js: the runtime hint stays slim and placeholder-driven.
identity-injection.test.js: identity and config.user.language must be injected into the super-agent prompt.
setup.js: provider, model, channels, and language belong to machine setup.

That is enough structure for me. Anything thicker starts to look like a second project.

APX is live: the personal assistant that orchestrates my Claude, Codex and Fable sessions

Manuel Bruña — Mon, 06 Jul 2026 13:00:04 +0000

For the last few months my daily work has been spread across a growing pile of AI coding tools — Claude Code in one terminal, Codex in another, Fable somewhere else, each with its own sessions, its own context, its own MCP servers and its own way of remembering (or forgetting) what I was doing. It worked, but I was the glue holding it all together. Every context switch cost me something.

So I built APX — and it's now live and running really well.

What APX actually is

APX is a local daemon that acts as my personal assistant for working with AI agents. Instead of me jumping between CLIs, APX sits in front of all of them and orchestrates the whole thing from one place.

In practice that means it can:

Manage sessions across Claude, Codex and Fable — start them, route work to the right runtime, and keep track of what each one is doing.
Schedule tasks so work runs when it should, not only when I happen to be sitting at the keyboard.
Organize everything: projects, agents, MCP servers and artifacts, all in one coherent structure instead of scattered configs.

The tagline in my head was simple: stop being the glue. Let one assistant hold the context so I can stay on the actual problem.

The problem it solves

If you use more than one AI CLI seriously, you already know the pain:

Each tool has its own notion of a "session," and none of them talk to each other.
MCP servers get re-declared per tool, per project, with subtly different scopes.
Your agents and prompts live in a dozen folders and README files.
When you want something to run later — or run in a different runtime — you're doing it by hand.

APX turns that into a single control plane. One place to see the agents, one place to register MCPs, one place to hand a task to whichever runtime fits it best.

How I use it day to day

The part that changed my workflow the most is being able to delegate a task to any runtime without re-setting-up my whole environment. I can hand a task to the local super-agent, or route it to Claude, Codex or another CLI — same projects, same agents, same MCPs underneath.

On top of that, the scheduling piece means the boring recurring work (status checks, routine jobs, follow-ups) just happens. I stopped being the cron job.

And because projects, agents and artifacts are organized in one model, onboarding a new agent or spinning up a new project is minutes, not an afternoon of copy-pasting config.

It's open source

APX is open and you can dig into it here:

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

If you're juggling multiple AI CLIs and feel like you are the integration layer, this is exactly the itch APX scratches. I'd genuinely love feedback, issues and ideas — this is the tool I use every single day, so it keeps getting better.

More coming soon. If you want to see it in action, I'm posting demos on my channels as Tecno Manu.

codex #ai #ia #claude #fable #agents

DEV Community: Manuel Bruña

Project Tasks Belong in APX, Not APC

Project Tasks Belong in APX, Not APC

I Stopped Treating the Web Admin as a Separate Product

I Stopped Treating the Web Admin as a Separate Product

What APX actually is

Where the drift showed up

The browser is good at browsing

What I changed in practice

The real lesson

Source notes

Project Config Should Travel With APC

Project Config Should Travel With APC

Skill Bodies Should Load on Demand

Skill Bodies Should Load on Demand

Path-Scoped Rules Belong in APC

Path-Scoped Rules Belong in APC

One repo, different rule zones

Why APC should own these rules

Why this also helps APX

Practical example

Bottom line

Project Skills Should Override Global Skills

Project Skills Should Override Global Skills

Three skill lanes, one precedence order

Why APC needs the top slot

Why global skills still matter

Why built-in skills stay as the safety net

On-demand loading keeps prompt cost low

Practical rule

Bottom line

You're not 'a programmer' anymore. You're one of these 5 archetypes.

The 5 archetypes

🧪 1. Prototyper — the spark

🏗️ 2. Builder — makes it real

🧹 3. Sweeper — the one who subtracts

📈 4. Grower — pushes toward product-market fit

🛠️ 5. Maintainer — the silent hero

The detail almost nobody sees

So… which one are you?

A Stable Project ID Keeps APC Portable and APX Local

A Stable Project ID Keeps APC Portable and APX Local

project.json gives the project a durable identity

Why that matters in daily work

Portable definition, local runtime

One practical rule

Bottom line

Agent Slugs Are the Smallest Handoff Key Between APC and APX

Agent Slugs Are the Smallest Handoff Key Between APC and APX

Why this matters

What should stay stable

APC side, APX side

Practical rule

Not Every Memory Belongs in APC

Not Every Memory Belongs in APC

APC memory: portable, curated, team-safe

APX memory: local, operational, runtime-owned

Practical rule: decide by visibility, not by format

Why APC and APX fit together here

APX Works Best When the Bridge Stays Thin

APX Works Best When the Bridge Stays Thin

What the bridge really does

Identity is not the same as context

Setup is not initialization

What changed for me

Why I still like the split

Source notes

APX is live: the personal assistant that orchestrates my Claude, Codex and Fable sessions

What APX actually is

The problem it solves

How I use it day to day

It's open source

codex #ai #ia #claude #fable #agents

`project.json` gives the project a durable identity