Project Structure

Agent definitions, Plugin configuration, and runtime data use user-level files. A project directory is only a Workspace containing project env, Skills, and business source files.

Directory layout

my-project/
├── .env                 # project environment variables
├── .agents/
│   └── skills/          # user-managed, versioned Skills
└── src/                 # application code (optional)

Global config

The user-level configuration layout is:

~/.downcity/
├── agents/<agent_id>/
│   ├── agent.json
│   ├── SOUL.md
│   └── sessions/
│       ├── <session_id>/
│       ├── archived-sessions/
│       └── logs/
├── plugins/<plugin_id>/config.toml
├── runtimes/city/
└── downcity.db

downcity.db stores Workspace IDs and paths, tokens, and platform state. It does not store Agent definitions, Plugin configuration, or Agent-to-Workspace bindings. CLI and Desktop read the same files and database.

agent_id and workspace_id are independent global identities. A Session receives a Workspace only for a concrete execution. CLI City daemon state lives in ~/.downcity/runtimes/city/; Sessions live under ~/.downcity/agents/<agent_id>/sessions/. A Session's meta.json records workspace_id only when a Workspace was supplied.

Project assets

Global Env is stored separately in ~/.downcity/.env. Project .env overrides Global Env, while explicit process environment variables have the highest priority. Project .env is added to .gitignore by default. .agents/skills is the only user-managed Agent capability asset intended for version control.

Runtime data

Downcity does not create <project>/.downcity/. Agent runtime data is centralized under the City-provided storage scope agents/<agent_id>/; without a City, it remains in memory. Plugin-owned data uses the Agent-level scope exposed through PluginContext.

Continue with:

• Project Init
• Agent SDK