Proyectos

Un proyecto es cualquier directorio que contiene un archivo AGENTS.md y un archivo .apc/project.json. Una vez registrado con apx project add, el daemon lo rastrea y APX mantiene todo su estado de runtime bajo ~/.apx/projects/<id>/.

Dos tipos de almacenamiento

APX impone una separación tajante entre lo que corresponde a tu repositorio y lo que corresponde a tu máquina:

Ubicación	Qué contiene	¿Commiteado?
`<repo>/.apc/`	Definiciones de agentes, skills, hints de MCP, config del proyecto	Sí
`~/.apx/projects/<id>/`	Sesiones, conversaciones, mensajes, cachés, logs de tareas	Nunca

Esto significa que la definición del proyecto es portable — cloná el repo en otra máquina y apx project add . la retoma. El estado de runtime queda local.

Disposiciones

Commiteado — el árbol `.apc/`

Directorioproject-root/
- AGENTS.md índice de agentes autogenerado; leído por Codex, Claude, etc.
- Directorio.apc/
  - project.json metadatos del proyecto y apx_id estable
  - config.json overrides de config a nivel de proyecto (nunca guardes secretos acá)
  - Directorioagents/
    <slug>.md un archivo por agente — rol, modelo, skills, descripción
  - mcps.json hints de MCP compartidos para este proyecto (sin tokens)
  - Directorioskills/ prompts de skills reutilizables locales al proyecto
    …
  - Directoriocommands/ slash commands personalizados
    …

Local — el árbol de estado de runtime

Directorio~/.apx/
- config.json config global — engines, proveedores, ajustes del daemon
- identity.json nombre de display del asistente (default “APX”)
- Directorioprojects/
  - Directorio<apx-id>/
    Directoriomessages/ YYYY-MM-DD.jsonl — todos los canales de mensajes del proyecto
    …
    Directorioartifacts/ archivos producidos durante las sesiones
    …
    routines.json rutinas programadas para este proyecto
    Directoriotasks/ YYYY-MM.jsonl logs de tareas
    …
    Directorioagents/
    Directorio<slug>/
    memory.md hechos durables del agente (curados, nunca transcripciones crudas)
    Directoriosessions/ un .md por invocación de runtime
    …
    Directorioconversations/ hilos de conversación del LLM
    …
    Directoriodefault/
    Directoriosessions/ fallback cuando no hay un rol de agente activo
    …

El archivo `project.json`

Cada proyecto tiene un .apc/project.json que APX lee al registrar:

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

El apx_id se genera una sola vez (con apx init) y no debe cambiarse — es la clave permanente que vincula .apc/ con ~/.apx/projects/<apx_id>/.

Comandos

Registrar un proyecto

apx project add .                   # register current directory
apx project add /path/to/repo       # register an explicit path

APX lee AGENTS.md y .apc/project.json durante el registro. Si falta cualquiera de los dos archivos, el comando sale con un error — usá apx init para scaffoldear un proyecto nuevo primero.

Listar proyectos registrados

apx project list                    # name, id, path, agent count
apx project list -l                 # long form — also shows storagePath

apx

$ apx project list -l
ID  NAME            AGENTS  PATH                    STORAGE
0   Base            1       —                       ~/.apx/projects/0
1   First Project   5       ~/code/first-project    ~/.apx/projects/1
2   Acme Store      4       ~/code/acme-store       ~/.apx/projects/2
3   Data Pipeline   3       ~/code/data-pipeline    ~/.apx/projects/3

apx project list — proyectos registrados con id, path y cantidad de agentes

Remover y reconstruir

apx project remove <id|name|path>   # unregister (does not touch files)
apx project rebuild <id|name|path>  # re-scan .apc/ from disk (use after moving the repo)

Config por proyecto

La configuración a nivel de proyecto vive en .apc/config.json y sobrescribe la global ~/.apx/config.json sólo para ese proyecto. Usá sintaxis de claves con puntos:

apx project config show <project>                          # merged effective + project-only view
apx project config show <project> --key super_agent.model  # one key
apx project config set  <project> super_agent.model groq:llama-3.3-70b-versatile
apx project config set  <project> super_agent.permission_mode total
apx project config set  <project> telegram.route_to_agent reviewer
apx project config unset <project> super_agent.model       # fall back to global value
apx project config edit <project>                          # open $EDITOR on the project JSON

Cada escritura dispara un reload del daemon — no hace falta reiniciar.

Resolviendo el argumento `<project>`

Cualquier comando que acepte <project> acepta cualquiera de estas formas:

Id numérico: 1
Nombre exacto de project.json: my-app
Path absoluto: /home/user/repos/my-app
Path relativo desde el directorio actual

Si no estás seguro del id o el nombre, corré apx project list primero.

El flag de pin `--project`

La mayoría de los subcomandos de apx aceptan --project <name|id|path> para apuntar a un proyecto registrado específico en lugar de inferirlo desde el directorio actual.

apx agent list --project my-app
apx session list --project my-app
apx messages tail --project my-app

El proyecto default

APX mantiene un proyecto incorporado con id default (~/.apx/projects/default/). Este es el workspace de borrador del super-agente — se usa cuando no hay ningún proyecto activo o direccionado explícitamente. No lo uses para trabajo real; se comparte entre todos los contextos.

Agentes — definí personas dentro de un proyecto.
Configuración — referencia de config global y a nivel de proyecto.