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
│   └── workspaces/<workspace_id>/
│       ├── sessions/
│       ├── 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 profiles, or Agent-to-Workspace bindings. CLI and Desktop read the same files and database.

agent_id and workspace_id are independent global identities. An Agent enters a Workspace only for a concrete execution. CLI City daemon state lives in ~/.downcity/runtimes/city/; Sessions live under ~/.downcity/agents/<agent_id>/workspaces/<workspace_id>/sessions/.

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/. AgentWorkspace runtime data is centralized under ~/.downcity/agents/<agent_id>/workspaces/<workspace_id>/; Plugin-owned data follows the storage scope exposed by its current AgentWorkspace context.

Continue with:

• Project Init
• Agent SDK