DEV Community

massiron
massiron

Posted on • Originally published at massiron.com

Build a Controllable AI Agent That Plans Before It Acts: deepstrain Tutorial

#deepstrain

The Problem: AI Agents That Just Break Things

Every AI coding agent I've tried follows the same pattern: you give it a task, it starts spamming tools in some invisible loop, and you pray it doesn't delete your node_modules or commit garbage to main. When it fails, you have no idea why — no logs, no decision trail, just a broken repo.

deepstrain solves this by treating AI execution like an operating system: the agent writes a plan first, you review it, then it executes step-by-step with full inspectability. No black boxes, no vendor lock-in, no data leaving your machine.

What We're Building

By the end of this tutorial, you'll have a working AI agent that:

  • Reads your local codebase
  • Generates a human-readable plan before touching any files
  • Executes refactoring tasks with full audit logs
  • Works with any model — local (Ollama) or cloud (GPT-4o, Claude, DeepSeek)

Step 1: Install

deepstrain is on PyPI. You need Python 3.10+.

pip install deepstrain
Enter fullscreen mode Exit fullscreen mode

That's it. No Docker, no cloud account, no API key required if you use Ollama locally.

Step 2: Configure a Model

deepstrain is model-agnostic. For this tutorial, we'll use Ollama with llama3.2 (3B, runs on a laptop):

# Start Ollama if you haven't already
ollama serve &

# Pull a model
ollama pull llama3.2
Enter fullscreen mode Exit fullscreen mode

Now tell deepstrain to use it:

deepstrain config --model ollama/llama3.2
Enter fullscreen mode Exit fullscreen mode

Or use a cloud model with your own key:

deepstrain config --model openai/gpt-4o --api-key sk-...
Enter fullscreen mode Exit fullscreen mode

Step 3: Run Your First Task

Let's do something harmless — ask the agent to analyze a Python file in your current directory:

deepstrain run "Analyze all .py files in this directory and summarize their functions"
Enter fullscreen mode Exit fullscreen mode

You'll see something like this:

[PLAN] deepstrain will:
  1. List .py files using bash tool
  2. Read each file using file I/O tool
  3. Extract function definitions using atlas (deterministic code analysis)
  4. Summarize findings in a report

Review plan? [Y/n]:
Enter fullscreen mode Exit fullscreen mode

Press Y to approve. The agent then executes each step, logging every tool call with timestamps and context.

Step 4: Inspect the Cognition

after execution, deepstrain writes a full session log to ~/.deepstrain/logs/. Open the latest one:

cat ~/.deepstrain/logs/session_$(date +%Y%m%d).log
Enter fullscreen mode Exit fullscreen mode

You'll see:

  • Every decision the agent made
  • Each tool call with input/output
  • Stack traces for any errors (no silent crashes)
  • The exact model response that led to each action

Step 5: Try a Real Refactoring Task

Now let's actually modify code. deepstrain has 52 built-in tools including git, bash, and file I/O. Here's a safe refactoring task:

deepstrain run "In all .py files, rename all instances of 'temp_var' to 'temporary_variable'"
Enter fullscreen mode Exit fullscreen mode

The agent will:

  1. Plan the change (e.g., "Use sed via bash, then verify with git diff")
  2. Show you the plan
  3. Execute only after your approval
  4. Log every change made

What Makes This Different

  • Plan-first execution: The agent writes a plan before touching files. You approve or reject. No surprise tool-spam.
  • Inspectable cognition: Every decision is logged. You can replay the agent's reasoning.
  • Model-agnostic: Use Ollama (free, local), GPT-4o, Claude, DeepSeek — swap with one config command.
  • Antifragile: Rotating error logs, graceful degradation. If a tool fails, the agent retries or asks for help — never crashes silently.
  • Free to start: pip install deepstrain gives you read-only tools immediately. Pro license ($9/mo) unlocks write tools (file modification, git push) with HMAC activation.

Limitations to Know

  • deepstrain is terminal-native. No GUI, no VS Code extension (yet).
  • Complex multi-step tasks can be slow with small local models (e.g., 3B parameter models). Use GPT-4o or DeepSeek for production work.
  • The plan-first flow adds friction. It's intentional — you're supposed to review before execution.

Next Steps

  • Browse the 19 capability domains: deepstrain capabilities list
  • Try an MCP server tool: deepstrain run "Use MCP to query a SQLite database"
  • Set up CI/CD integration: deepstrain can run in GitHub Actions with a headless mode 
# Start with a trial key (no credit card)
deepstrain auth --trial

# Or go Pro
pip install deepstrain-pro-license  # $9/mo
Enter fullscreen mode Exit fullscreen mode

Repo: https://github.com/mete-dotcom/deepstrain
Docs: https://massiron.com/deepstrain

Install today and run your first controllable AI agent:

pip install deepstrain
deepstrain run "What's the weather in Tokyo?"  # uses web search tool
Enter fullscreen mode Exit fullscreen mode

Top comments (0)