Your First Project

This guide takes you from an empty directory to a working SPT project with vector storage, agent orchestration, and SPT Wire messaging.

1. Initialize

Create a directory and run spt init:

mkdir myproject && cd myproject
git init
spt init

The default initialization creates:

myproject/
├── CLAUDE.md                # Swarm guidance and project config
├── .mcp.json                # MCP server configuration
├── .claude/
│   ├── settings.json        # Claude Code hook configuration
│   ├── skills/              # Reusable skill definitions
│   ├── commands/            # Custom slash commands
│   ├── agents/              # Agent definitions
│   └── helpers/             # Utility scripts
└── .sptflo/
    ├── config.yaml          # Runtime configuration
    ├── data/                # Persistent storage
    ├── logs/                # Execution logs
    └── sessions/            # Session history

Presets

Use spt init --minimal for just the essentials, or spt init --full for every component including embeddings. Run spt init wizard for an interactive setup that walks you through each option.

Start Services

Initialize and start the daemon, memory database, and swarm in one step:

spt init --start-all

Or start them individually after init:

spt daemon start           # Background workers
spt memory init            # Initialize memory database
spt swarm init             # Initialize swarm topology

2. Use the Vector Database

Store and query patterns with the SptDB examples. These use the spt CLI under the hood:

# Store patterns in batch
node -e "
const { execSync } = require('child_process');

const patterns = [
  { key: 'auth-jwt', value: 'JWT token validation with RS256 signing' },
  { key: 'auth-oauth', value: 'OAuth 2.0 authorization code flow' },
  { key: 'cache-redis', value: 'Redis cache-aside pattern with TTL' },
  { key: 'cache-lru', value: 'In-memory LRU cache for hot paths' },
];

for (const p of patterns) {
  execSync(
    \`npx spt memory store \"\${p.key}\" \"\${p.value}\" --namespace demo\`,
    { stdio: 'pipe' }
  );
  console.log('Stored:', p.key);
}
"

# Query by semantic similarity
npx spt memory search "authentication patterns" --namespace demo

For production usage, see the SptDB examples:

# Batch queries with throughput metrics
node examples/sptdb/batch-query.js '["auth","cache"]' demo

# Cached queries with TTL (up to 2000x speedup on repeated queries)
node examples/sptdb/cached-query.js "auth patterns" demo

3. Run a Swarm

Launch a multi-agent swarm to collaboratively work on a task:

spt swarm init --topology hierarchical
spt swarm start --agents 4 --task "Analyze the project structure and suggest improvements"

The swarm creates four specialized agents (coordinator, analyst, coder, optimizer) that communicate through shared memory. Check status with:

spt swarm status

For a complete multi-agent deployment example with memory coordination:

npx tsx examples/swarm/multi-agent-deployment.ts

4. SPT Wire Messaging

SPT Wire provides the DID-addressed QUIC transport backbone for inter-agent communication. SPT uses a DID-prefix subject hierarchy for routing:

swarm.agent.{name}.status    — Agent heartbeat and status
swarm.agent.{name}.command   — Direct commands to an agent
swarm.task.assigned          — New task assignments
swarm.task.completed         — Task completion events
swarm.memory.update          — Shared memory updates
swarm.memory.conflict        — Memory conflict alerts
swarm.metrics.{agent}        — Per-agent performance metrics

Try the simulated pub/sub demo:

node examples/nats/swarm-pubsub.js

For persistent task queues with at-least-once delivery:

node examples/nats/jetstream-task-queue.js

For real-time agent state management with watches:

node examples/nats/kv-agent-state.js

SPT Wire

SPT Wire (spt-wire crate) replaces NATS as the core transport. It provides DID-authenticated QUIC with scope-aware routing, pub/sub, and store-and-forward for offline delivery. See ADR-088 and ADR-101.

5. Claude Code Integration

If you have Claude Code installed, SPT's MCP tools are available directly in your sessions:

# Register the MCP server (one-time)
claude mcp add spt -- spt mcp start

# Start a Claude Code session in your project
claude

Inside Claude Code, you can ask it to use SPT tools:

> Use spt to initialize a swarm with 3 agents and analyze this codebase
> Store the analysis results in spt memory under the "architecture" namespace

Next Steps

• Browse the Examples for vector database, swarm, and transport patterns
• Read the Architecture Overview for system design details
• Explore the SPTFlo Reference for the complete CLI and MCP tool reference
• Check out the Guides for in-depth development workflows