Proyectos
Un proyecto es un lugar donde pasa el trabajo: un repo, una empresa, los trámites de tu vida. En APX es una carpeta
que sigue APC (Agent Project Context), un estándar abierto: un AGENTS.md en la raíz y una carpeta .apc/ al
lado. Tus agentes, sus instrucciones, las skills y los servidores MCP del proyecto viven en esos archivos, así que
viajan con la carpeta, aparecen en git diff y cualquier herramienta que entienda el estándar los puede leer.
Qué hay en un proyecto
Sección titulada «Qué hay en un proyecto»Directorioacme-store/
- AGENTS.md qué es el proyecto y cómo se trabaja en él
Directorio.apc/
- project.json nombre, descripción y tipo
- memory.md tus notas fijas para los agentes del proyecto
- organization.json áreas y roles (empresas)
- mcps.json servidores MCP del proyecto
Directorioagents/
- lucia.md
- tomas.md
- vera.md
Directorio.archived/ los agentes que sacás terminan acá, nunca se borran
- …
Directorioskills/
Directorioweekly-report/
- SKILL.md
Directoriosrc/
- …
- …
| Archivo | Qué hace APX con él |
|---|---|
AGENTS.md | Contexto del proyecto que leen todos sus agentes, entero: cuánto mide lo decidís vos. Solo un archivo de más de 200.000 caracteres (un límite de seguridad) se recorta al principio y el final; los agentes saben qué líneas quedaron afuera y las leen cuando las necesitan, y la configuración del proyecto en el panel (y apx projects list) lo avisa. |
.apc/project.json | name, description y kind. Un apx_id commiteado mantiene estable el id del proyecto; un clon o worktree al lado del original recibe uno propio. |
.apc/agents/<slug>.md | Un agente cada uno. Mirá Agentes. |
.apc/memory.md | Notas que escribís a mano; los agentes las leen y nunca las escriben. Reciben el archivo entero hasta el mismo límite de seguridad de 200.000 caracteres; por encima, reciben el principio, el final y un marcador de omisión. El aviso de recorte del panel y la CLI cubre solo AGENTS.md, no estas notas. |
.apc/skills/<name>/SKILL.md | Skills que sólo reciben los agentes de este proyecto. Mirá Skills. |
.apc/mcps.json | {"mcpServers": …} del proyecto, sin secretos adentro. Cada servidor tiene que estar aprobado antes de correr. Mirá Servidores MCP. |
.apc/organization.json | Áreas y roles de una empresa (hasta 40 áreas y 200 roles). |
APX vigila .apc/ y AGENTS.md. Editás un archivo en tu editor, lo guardás, y la app lo toma un momento después.
Tipos de proyecto
Sección titulada «Tipos de proyecto»Cada proyecto tiene un tipo, que elegís al sumarlo o después en su configuración:
| Tipo | Para |
|---|---|
| Personal | Tus cosas. Sin equipo ni estructura. |
| App | Una aplicación que usa gente. |
| Empresa | Áreas, roles y un equipo ejecutivo. |
| Software | Una biblioteca o CLI que usan otros programas. |
| Otro | Ninguno de los anteriores. |
Sólo una Empresa tiene áreas y roles. Importar el equipo ejecutivo convierte un proyecto en empresa por sí solo.
Sumar un proyecto
Sección titulada «Sumar un proyecto»- En la barra lateral, tocá Nuevo proyecto.
- En Dónde vive, elegí En una carpeta y buscá el repo o la carpeta, o Sin carpeta para crear una dentro
de la carpeta de APX (
~/.apx/v2/projects/<name>). - Ponele nombre (si lo dejás vacío, el de la carpeta), tipo y descripción, y tocá Sumar.
Si la carpeta no tiene AGENTS.md, APX escribe uno de una línea y crea .apc/. No toca nada más de tu carpeta.
Registrá una carpeta que ya tenga AGENTS.md o .apc/:
❯ apx projects register ~/work/acme-store Acme Store (p_3f9a1c0d7e21): 4 agents
Listalos. Un ! quiere decir que la carpeta no está en el disco ahora (la moviste, el disco está desenchufado):
❯ apx projects p_3f9a1c0d7e21 Acme Store company p_8b20e4f1a9c3 ! Northwind site app
Releé los archivos a mano, de todos los proyectos o de uno:
❯ apx projects sync p_3f9a1c0d7e21 read 1 projects · 4 agents · 0 archived
Preparación opcional
Sección titulada «Preparación opcional»Revisar contexto del proyecto ayuda a convertir el contexto, memoria, tareas y chats existentes en un primer paso concreto. Podés preparar un resumen o enviárselo al agente que lidera el proyecto (o a Home) para empezar. Las ofertas proactivas se activan solo si querés; cerrar la ayuda nunca bloquea el chat ni la creación de agentes.
Al crear un agente, Revisar borrador con el contexto del proyecto puede proponer instrucciones faltantes. Revisá el antes y el después completos y aceptá explícitamente para aplicarlas al borrador sin guardar y sin cambios desde la revisión. No reescribe agentes existentes ni otorga permisos; guardar el agente sigue siendo otra acción. Si cambiaste el borrador mientras tanto, revisalo otra vez. El texto del proyecto en el resumen sigue siendo información de referencia, no autorización.
Carpetas de solo lectura
Sección titulada «Carpetas de solo lectura»Un agente lee y escribe solo en la carpeta donde trabaja y en su carpeta temporal. Cuando una tarea necesita otra
carpeta, por ejemplo otro checkout para comparar o una carpeta de documentación, sumala como carpeta de solo
lectura del proyecto. Sus agentes, y los ayudantes a los que delegan, pueden leerla con file_read y con comandos
como cat, rg o git log, y copiar de ella a su propia carpeta. APX rechaza toda escritura que puede ver ahí,
desde una herramienta de archivos o en un comando. Esa revisión es lo que protege la carpeta, no un sandbox del sistema
operativo: un script que arma una ruta mientras corre no se detecta. Cada turno le dice al agente cuáles son.
Abrí la configuración del proyecto (el engranaje en su encabezado). En Carpetas de solo lectura, escribí una ruta absoluta (o elegila en la app de escritorio) y tocá Agregar. Tocá la × al lado de una carpeta para quitarla. Cada cambio se guarda en el momento.
❯ apx projects folders add p_3f9a1c0d7e21 ~/work/acme-store-v1 ~/work/acme-store-v1
apx projects folders list <project> las muestra y apx projects folders rm <project> <folder> quita una.
Una carpeta de solo lectura tiene que existir y ser una carpeta. No puede ser la carpeta de APX, una carpeta adentro de
ella ni una que la contenga, y no puede estar adentro de la carpeta del proyecto (ahí los agentes ya leen y escriben).
APX guarda la lista en su base de datos, no en .apc/, así que un repo no puede ampliar lo que leen sus agentes.
Cuando un agente lee fuera de sus carpetas en un proyecto (un ls .. para mirar alrededor, un archivo de otro checkout
al lado), no se queda trabado: el chat muestra una tarjeta, Fausto quiere leer y la carpeta, con Solo esta vez
(esa llamada lee ahí), Permitir leerla en este proyecto (la carpeta pasa a ser de solo lectura, con los controles de
arriba) y No. Escribir fuera de sus carpetas sigue rechazado, igual que leer en un chat sin proyecto.
Un agente con autonomía total (o con su regla Actuar afuera en tu nombre en Sin preguntar) lee y cambia cualquier carpeta de la computadora, en un chat de proyecto o en uno sin proyecto, sin tarjeta, y no se suma nada. Dos cosas siguen cerradas igual: la carpeta propia de APX, y las carpetas de solo lectura del proyecto, que lee y nunca cambia.
El proyecto base
Sección titulada «El proyecto base»Home y tus agentes globales viven en el proyecto base. No tiene carpeta: APX guarda su nombre y su tipo, sus agentes trabajan en cualquier lado y no se puede borrar. Le ponés nombre durante la configuración y lo podés cambiar después; sigue siendo el proyecto base se llame como se llame. Cuando quieras agentes que trabajen en una carpeta puntual, creá un proyecto para esa carpeta.
Lo que APX guarda de su lado
Sección titulada «Lo que APX guarda de su lado»La carpeta del proyecto es tuya. Todo lo que APX necesita y no es parte del estándar queda en el home de APX
(~/.apx/v2):
- La base de datos (
apx.db): chats, turnos, tareas, rutinas, notas, widgets y un índice de los agentes de tus proyectos. Los archivos siguen mandando en la definición de los agentes; el índice se rearma desde ellos. - El lado de APX del proyecto:
~/.apx/v2/projects/<name>para un proyecto que APX creó sin carpeta en otro lado, y~/.apx/v2/projects/<id>para todos los demás. Los agentes de afuera (Claude Code, Codex) en un chat del proyecto trabajan ahí, nunca en tu carpeta, así los archivos temporales de un proyecto no caen entre los de otro.
Los hilos de código son la excepción: trabajan en la carpeta de tu proyecto a propósito. Mirá Conversaciones.
Adentro de un proyecto
Sección titulada «Adentro de un proyecto»Abrí un proyecto desde la barra lateral y vas a ver sus pestañas: Resumen, Chats, Agentes, Tareas, Rutinas, Archivos, Memoria y Recursos. El Resumen es el proyecto de un vistazo: un Board con los widgets que fijaste, lo que está corriendo ahora, el equipo, algunos números y los últimos chats.
