Architecture of cosmicstack-labs/mercury-agent
cosmicstack-labs/mercury-agent is 733 source files holding 4,898 symbols across 6 modules, written mainly in TypeScript, JavaScript, Shell. The largest module is src, with 427 files, and 8 files are entry points into the dependency graph.
How mercury-agent fits together
Messages enter through channels: the terminal, Telegram, Discord, Slack, Signal and a local web dashboard all reach the same agent. src/channels/cli.ts implements the terminal channel, and src/index.ts is one of the entry points for starting the program. A single background process owns the channels, bots and web dashboard, so running mercury in a terminal attaches to that process instead of starting a separate one. The agent logic lives in src/core/agent.ts, and each action it takes is checked against permission rules and a daily token budget. src/bots holds the code that defines and checks Mercury Bots, the persistent specialists that run on schedules and deliver finished files. The ui directory holds the browser UI foundation, with src/ui/App.tsx as one of its entry points, and website holds the Docusaurus documentation site. scripts holds build-adjacent tooling such as vendor patching and native dependency checks.
Largest modules
- src: 427 files and 75,039 lines of code
- ui: 70 files and 16,313 lines of code
- docs: 69 files and 391 lines of code
- scripts: 17 files and 1,801 lines of code
- website: 14 files and 2,111 lines of code
- root: 3 files and 121 lines of code
Languages
By file count: TypeScript 509 files, JavaScript 82 files, Shell 8 files, Python 1 file.
Documentation
Repowise documents mercury-agent in 671 pages generated from the source, 36 of them written explanations of the repository and its modules. Module guides include:
- src/providers: AI Provider Integrations
- src: Agent Initialization
- src/core: Agent Orchestration Core
More on mercury-agent: summary and FAQ, codebase overview, code health.
Related guide: Best dependency graph tools for monorepos