Back to guides
6
3 min

Deploy Locally

Your CLI Assistant

From Project to Product

You've built API calls, tool use, email triage, research, and memory. Now you package everything into a CLI assistant you'll actually run every day. This is where engineering meets UX.

Code Organization

A well-structured assistant separates concerns:

FileResponsibility
`src/assistant.ts`Main loop, message handling, streaming
`src/tools.ts`Tool definitions and execution handlers
`src/memory.ts`Conversation history, summarization, persistence
`src/config.ts`User preferences, contacts, settings
`src/cli.ts`Input parsing, command routing, output formatting

Each file has a single job. When you need to fix email triage, you know to look in tools.ts. When streaming breaks, it's in assistant.ts.

Slash Commands

A CLI assistant needs more than freeform chat. Slash commands give users quick access to common actions:

CommandAction
`/email`Show unread email summary with triage
`/calendar`Show today's schedule
`/tasks`List active tasks by priority
`/research [topic]`Search bookmarks and generate a brief
`/prefs`Show or update user preferences
`/help`List available commands

Commands should be fast — they call specific tools directly instead of going through the full AI reasoning loop.

Startup Briefing

The first thing your assistant does on launch matters. A startup briefing answers: "What do I need to know right now?"

The pattern:

  • Load preferences and contacts
  • Count unread emails, flag critical ones
  • Get today's calendar events
  • Check for overdue tasks
  • Present a 4-5 line summary

    • > Good morning, Alex. You have 4 unread emails (1 critical: production alert). Your day starts with a 10am meeting with Sarah Chen. You have 2 overdue tasks on the infrastructure project. Type /email to triage or just ask me anything.

    This makes the assistant immediately useful — no "how can I help you?" required.

    Error Handling

    Production-quality error handling covers five scenarios:

    ErrorHow to Handle
    API key missing/invalidClear message: "Set ANTHROPIC_API_KEY in your environment"
    Rate limited (429)Wait and retry with backoff, show "Thinking..."
    Network timeoutRetry once, then suggest checking connection
    Data file missingSkip that tool gracefully, tell the user
    Malformed tool responseLog the error, ask Claude to try again

    Never crash on a recoverable error. Never show a raw stack trace to the user.

    Output Formatting

    Terminal output should be easy to scan:

  • Use bold for headers and important items (ANSI escape codes)
  • Use color for priority levels (red = critical, yellow = action needed)
  • Indent sub-items for hierarchy
  • Add blank lines between sections
  • Keep individual responses under 20 lines — summarize, don't dump

    • Testing Your Assistant

    Before you call it "done," test these scenarios:

  • Cold start with no previous history
  • A 20+ turn conversation (tests context management)
  • A question that requires 3+ tool calls in sequence
  • Invalid input (empty message, random characters)
  • Asking about data that doesn't exist

    • What You've Built

    By the end of this course, you have a fully functional AI assistant that:

  • Streams responses from the Claude API
  • Calls tools to read emails, check calendar, search bookmarks, manage tasks
  • Triages email by priority and drafts context-aware replies
  • Searches saved research and produces cited briefs
  • Remembers conversations and knows your preferences
  • Runs as a polished CLI tool on your machine

    • This is the same architecture that powers production AI assistants — the difference is scale, not pattern.

    Key Takeaways

  • Separate concerns: assistant logic, tools, memory, config, and CLI should be in different files.
  • Slash commands give users fast access to common actions without going through AI reasoning.
  • A startup briefing makes the assistant immediately useful — no cold start.
  • Handle errors gracefully: never crash, never show stack traces, always guide the user.

    • This is chapter 6 of Build Your AI Assistant with Claude.

    Get the full hands-on course — free during early access. Build the complete system. Your projects become your portfolio.

    View course details
    Previous

    Ch. 5: Memory & Context