# Getting Started with SOPHIAClaw

## What You're Getting

SOPHIAClaw is an AI assistant that actually gives a damn about your business. Unlike other AI tools that operate in black boxes, SOPHIAClaw shows you exactly what it's thinking, checks every action against your rules, and keeps your data under your control.

**Translation:** You get an AI assistant that won't accidentally delete your files, won't leak your data, and won't make decisions you can't understand.

---

## 5-Minute Quick Start

### What You Need

- A computer running macOS, Linux, or Windows (WSL2)
- Node.js 22+ (we'll check this)
- About 30 minutes for initial setup

**Hardware requirements:**

- 4GB RAM minimum (8GB recommended)
- 2GB free disk space
- Internet connection

### Installation

```bash
# Install SOPHIAClaw globally
npm install -g sophiaclaw@latest

# Run the setup wizard
sophiaclaw onboard --install-daemon
```

The wizard will:

1. Check your system requirements
2. Set up the Gateway (the brain of the operation)
3. Configure your first messaging channel
4. Install as a background service (optional)

### First Conversation

Once installed, start chatting:

```bash
# Start the gateway
sophiaclaw gateway --port 37521

# In another terminal, send a message
sophiaclaw agent --message "Hello, what can you do?"
```

Or connect via:

- **Telegram:** Message @YourBotName
- **Discord:** Use /claw command in configupurple server
- **Web Dashboard:** http://localhost:3000

---

## Understanding What Just Happened

When you send a message to SOPHIAClaw, here's what happens behind the scenes:

1. **Intent Capture** - SOPHIA analyzes what you're asking for
2. **Policy Check** - It checks if this action is allowed (no accidental file deletions)
3. **Tool Selection** - It picks the right tool for the job
4. **Execution** - It does the work
5. **Audit Trail** - Everything is logged (you can review later)

**The key difference:** Traditional AI assistants skip step 2 and 5. SOPHIAClaw doesn't.

---

## Your First Real Task

Let's have SOPHIAClaw help with something useful:

```bash
sophiaclaw agent --message "Check my website getthalamus.ai and tell me if it's loading properly"
```

Behind the scenes:

- SOPHIA captures intent: "Check website status"
- Policy check: ✅ Web fetch is allowed
- Tool selected: Browser automation
- Execution: Fetches your website
- Response: "Your website is loading in 180ms with HTTP 200 OK"

---

## Common Tasks

### Check Emails

```bash
sophiaclaw agent --message "Check my business email for anything urgent"
```

### Draft a Response

```bash
sophiaclaw agent --message "Draft a professional response to this email: [paste email]"
```

### File Operations

```bash
sophiaclaw agent --message "List the files in my Documents/Obsidian Vault folder"
```

### Web Research

```bash
sophiaclaw agent --message "Search for best practices for AI governance in small businesses"
```

---

## Configuration

### Setting Up Channels

**Telegram:**

```bash
sophiaclaw channel add telegram --bot-token YOUR_BOT_TOKEN
```

**Discord:**

```bash
sophiaclaw channel add discord --bot-token YOUR_BOT_TOKEN
```

**Slack:**

```bash
sophiaclaw channel add slack --app-token YOUR_APP_TOKEN
```

### Setting Up Models

By default, SOPHIAClaw uses cost-optimized routing:

| Task Type        | Model Used    | Cost per 1K tokens |
| ---------------- | ------------- | ------------------ |
| Simple questions | Gemini Flash  | $0.0001            |
| Most tasks       | Claude Haiku  | $0.004             |
| Complex analysis | Claude Sonnet | $0.015             |
| Code generation  | Qwen Coder    | $0.002             |

Override for specific tasks:

```bash
sophiaclaw agent --message "Complex analysis task" --model claude-3.5-sonnet
```

---

## Governance in Action

See SOPHIA's governance at work:

### Check Audit Trail

```bash
sophiaclaw bulletin list --last 24h
```

Shows every action SOPHIAClaw took, with:

- What was requested
- What tools were used
- What the results were
- Any policy decisions made

### Review Intent History

```bash
sophiaclaw intent list --session <session-id>
```

See how SOPHIA understood your requests over time.

### Check Policy Violations

```bash
sophiaclaw policy violations --last 7d
```

See what actions were blocked and why.

---

## Cost Control

SOPHIAClaw tracks every API call:

```bash
# Check today's spending
sophiaclaw usage today

# Check this month
sophiaclaw usage month

# Set a daily budget alert
sophiaclaw config set daily_budget_limit 10
```

Typical daily usage for a small business:

- 20-30 queries: ~$0.50-$1.00
- Heavy usage (100+ queries): ~$3.00-$5.00

---

## Troubleshooting

### "Gateway not running"

```bash
sophiaclaw gateway start
# or
sophiaclaw gateway --port 37521 --verbose
```

### "Channel not responding"

```bash
# Check channel status
sophiaclaw channel list

# Re-verify the channel
sophiaclaw channel verify <channel-name>
```

### "Model not available"

```bash
# Check available models
sophiaclaw models list

# Test connectivity
sophiaclaw doctor
```

### Get Help

```bash
# Built-in help
sophiaclaw help

# Specific command help
sophiaclaw help agent

# Check system health
sophiaclaw doctor
```

---

## Next Steps

1. **Read the SMB Guide** - [FOR-SMB-OWNERS.md](./FOR-SMB-OWNERS.md)
2. **Understand Governance** - [governance.md](./governance.md)
3. **Learn Architecture** - [architecture.md](./architecture.md)
4. **Explore Features** - [features.md](./features.md)

---

## Support

- **Documentation:** https://docs.sophiaclaw.ai
- **Issues:** https://github.com/sophiaclaw/sophiaclaw/issues
- **Discord:** [Join the community](https://discord.gg/sophiaclaw)

---

<p align="center">
  <em>Remember: The future of AI is governed, not caged.</em>
</p>