Project Structure

When you download your agent from Agent Workshop, you receive a complete TypeScript project ready to build and run. This guide explains each file and directory.

Directory Overview

1my-agent/
2├── package.json          # Dependencies and npm scripts
3├── tsconfig.json         # TypeScript configuration
4├── src/
5│   ├── cli.ts           # CLI entry point
6│   ├── agent.ts         # Core agent logic
7│   ├── config.ts        # Configuration management
8│   ├── permissions.ts   # Permission system
9│   ├── mcp-config.ts    # MCP server management
10│   ├── planner.ts       # Planning mode support
11│   └── workflows.ts     # Workflow executor
12├── .claude/
13│   ├── CLAUDE.md        # Agent memory
14│   ├── commands/        # Slash commands
15│   ├── agents/          # Subagent definitions
16│   ├── skills/          # Skill definitions
17│   └── settings.json    # Hooks configuration
18├── .commands/           # Domain workflow definitions
19├── .plans/              # Plan storage directory
20├── .mcp.json            # MCP server configuration
21├── .env.example         # Environment template
22├── .gitignore           # Git ignore rules
23├── README.md            # Project documentation
24├── LICENSE              # License file
25└── scripts/
26    └── publish.sh       # NPM publish script

Core Files

package.json

NPM package configuration with dependencies and scripts.

1{
2  "name": "my-agent",
3  "version": "1.0.0",
4  "type": "module",
5  "main": "dist/cli.js",
6  "bin": {
7    "my-agent": "dist/cli.js"
8  },
9  "scripts": {
10    "build": "tsc",
11    "dev": "tsc --watch",
12    "start": "node dist/cli.js"
13  },
14  "dependencies": {
15    "@anthropic-ai/claude-code": "^0.1.53",
16    "commander": "^11.1.0",
17    "chalk": "^5.3.0",
18    "ora": "^8.0.1",
19    "inquirer": "^9.2.12",
20    "dotenv": "^16.3.1"
21  }
22}

src/cli.ts

The CLI entry point. Handles command-line arguments, interactive mode, and user input.

• Parses command-line arguments with Commander
• Manages interactive prompt loop
• Handles slash commands and special inputs
• Displays streaming responses

src/agent.ts

Core agent implementation. Defines the agent class with all configured tools.

• Agent initialization and configuration
• Tool definitions and implementations
• Message handling and response streaming
• Session management

src/config.ts

Configuration management. Loads and validates environment variables and settings.

• Environment variable loading
• API key validation
• Default value management

src/permissions.ts

Permission system implementation. Controls what tools can do based on permission level.

• Permission policies (restrictive, balanced, permissive)
• Path restrictions
• Command filtering
• User confirmation prompts

src/mcp-config.ts

MCP server management. Loads and connects to configured MCP servers.

• Server configuration loading from .mcp.json
• Transport handling (stdio, http, sse, sdk)
• Environment variable resolution

src/planner.ts

Planning mode support. Manages plan creation, storage, and execution.

• Plan file management in .plans/
• Plan listing and status
• Plan execution tracking

src/workflows.ts

Workflow executor. Runs domain-specific multi-step workflows.

• Workflow loading from .commands/
• Step-by-step execution
• Progress tracking

.claude/ Directory

Contains Claude Code-style lever configurations.

CLAUDE.md

Agent memory file. Loaded at the start of every conversation to provide persistent context.

commands/

Slash command definitions. Each .md file is a command template.

agents/

Subagent definitions. Each .md file defines a specialized subagent.

skills/

Skill definitions. Each subdirectory contains a SKILL.md file.

settings.json

Hooks configuration. Defines event-driven automations.

.commands/ Directory

Domain-specific workflow definitions. JSON files that define multi-step workflows for common tasks.

1{
2  "name": "code-audit",
3  "description": "Perform a comprehensive code audit",
4  "steps": [
5    {
6      "name": "scan",
7      "prompt": "Scan the codebase for security vulnerabilities"
8    },
9    {
10      "name": "analyze",
11      "prompt": "Analyze code quality and patterns"
12    },
13    {
14      "name": "report",
15      "prompt": "Generate audit report with findings"
16    }
17  ]
18}

Configuration Files

.mcp.json

MCP server configuration. Defines which MCP servers to connect to.

.env.example

Environment variable template. Copy to .env and fill in values.

1# API Keys
2ANTHROPIC_API_KEY=your-key-here
3# or
4OPENAI_API_KEY=your-key-here
5
6# Optional: MCP Server credentials
7GITHUB_TOKEN=
8DATABASE_URL=

tsconfig.json

TypeScript configuration. Targets ES2022 with module resolution for Node.