Quick Start Tutorial

Quick Start Tutorial

Get up and running with aistack in 5 minutes

What You'll Build

In this tutorial, you'll:

1. Install aistack
2. Spawn your first agent
3. Store and search memory
4. Run a simple task

Time required: ~5 minutes

Step 1: Installation (1 minute)

# Install aistack
npm install @blackms/aistack

# Initialize project
npx @blackms/aistack init

Create .env file:

ANTHROPIC_API_KEY=your_api_key_here

Step 2: Spawn Your First Agent (1 minute)

# Spawn a coder agent
npx @blackms/aistack agent spawn -t coder -n my-first-coder

# Verify it was created
npx @blackms/aistack agent list

Expected output:

Agents (1):
  - my-first-coder (coder) - Status: idle

Step 3: Store Knowledge in Memory (1 minute)

# Store a coding pattern
npx @blackms/aistack memory store \
  -k "pattern:singleton" \
  -c "Use singleton pattern for config management to ensure single instance"

# Store another pattern
npx @blackms/aistack memory store \
  -k "pattern:factory" \
  -c "Use factory pattern for creating objects with complex initialization"

Step 4: Search Memory (1 minute)

# Search for patterns
npx @blackms/aistack memory search -q "singleton"

Expected output:

Found 1 result(s):

1. pattern:singleton (score: 0.95)
   Use singleton pattern for config management to ensure single instance

Step 5: Run a Task with an Agent (1 minute)

# Run a simple task
npx @blackms/aistack agent run \
  -t coder \
  -p "Write a TypeScript function that validates email addresses"

The agent will:

1. Generate the function
2. Add error handling
3. Return the complete implementation

Using the MCP Integration

Connect to Claude Code

# Add aistack to Claude Code MCP
claude mcp add aistack -- npx @blackms/aistack mcp start

Use in Claude Code

In Claude Code, you can now:

# Ask Claude to spawn an agent
Can you spawn a coder agent using the agent_spawn tool?

# Ask Claude to store memory
Store this pattern in memory: "Use dependency injection for testability"

# Ask Claude to search memory
Search memory for "dependency injection"

Quick Example: Complete Workflow

Here's a complete workflow using the CLI:

# 1. Spawn specialized agents
npx @blackms/aistack agent spawn -t coder -n backend-coder
npx @blackms/aistack agent spawn -t tester -n test-writer

# 2. Store architectural decisions
npx @blackms/aistack memory store \
  -k "arch:api-design" \
  -c "REST API with versioned endpoints (/api/v1/...)" \
  -n "architecture"

# 3. Run code generation task
npx @blackms/aistack agent run \
  -t coder \
  -p "Create a REST API endpoint for user management" \
  --context "@memory:arch:api-design"

# 4. Check system status
npx @blackms/aistack status

Web Dashboard Quick Start

Start the visual dashboard:

npx @blackms/aistack web start

Open http://localhost:3001 and:

1. View active agents
2. Create tasks
3. Browse memory
4. Monitor system health

TypeScript API Quick Start

import { spawnAgent, getMemoryManager, getConfig } from '@blackms/aistack';

// Spawn an agent
const agent = spawnAgent('coder', {
  name: 'my-coder',
  metadata: { project: 'myapp' }
});

console.log(`Agent ${agent.name} spawned with ID: ${agent.id}`);

// Store memory
const memory = getMemoryManager(getConfig());
await memory.store('tip:testing', 'Always write tests for edge cases', {
  namespace: 'best-practices'
});

// Search memory
const results = await memory.search('testing');
console.log(`Found ${results.count} results`);

What's Next?

Now that you have the basics:

Learn More About Agents

• Understanding Agents - How agents work
• Agent Overview - All 11 agent types
• Coder Agent - Deep dive into the coder agent

Explore Memory System

• Memory System - Persistent storage explained
• Memory Tools - All memory operations

Try Advanced Features

• Code Review Workflow - Multi-agent code review
• Adversarial Testing - Adversarial review loop

Configure for Your Workflow

• Configuration Guide - All configuration options
• MCP Integration - Claude Code integration

Common First Tasks

Task 1: Documentation Generation

npx @blackms/aistack agent run \
  -t documentation \
  -p "Generate API documentation for this codebase" \
  --context "@file:./src/api.ts"

Task 2: Test Writing

npx @blackms/aistack agent run \
  -t tester \
  -p "Write unit tests for the authentication module" \
  --context "@file:./src/auth.ts"

Task 3: Code Review

npx @blackms/aistack agent run \
  -t reviewer \
  -p "Review this pull request for best practices" \
  --context "@file:./src/feature.ts"

Task 4: Adversarial Testing

# Start adversarial review loop
npx @blackms/aistack workflow run adversarial-review

Tips for Success

1. Start Simple: Begin with one agent type (coder or researcher)
2. Use Memory: Store patterns, decisions, and learnings as you go
3. Combine Agents: Use multiple specialized agents for complex tasks
4. Check Status: Use npx @blackms/aistack status frequently
5. Read Logs: Enable verbose logging with -v flag for debugging

Troubleshooting

Agent Won't Spawn

# Check system status
npx @blackms/aistack status

# Verify config
cat aistack.config.json

Memory Search Returns No Results

# List all memory entries
npx @blackms/aistack memory list

# Check if FTS5 is working
npx @blackms/aistack system health

MCP Not Working in Claude Code

# Verify MCP registration
claude mcp list

# Re-add if needed
claude mcp remove aistack
claude mcp add aistack -- npx @blackms/aistack mcp start

Next Tutorial

Continue with First Agent Tutorial for a deeper, interactive walkthrough.

---

See Also

• Installation
• Configuration Guide
• Troubleshooting
• CLI Commands