DEV Community

massiron
massiron

Posted on • Originally published at massiron.com

Build a Local AI Coding Agent That Actually Plans Before Acting: Deepstrain Tutorial

#deepstrain

Most AI coding agents are black boxes. You give them a task, they start spamming tools, and you pray they don't delete your src/ directory. If you've ever watched an agent blindly run rm -rf or hallucinate a file rename, you know the pain.

Deepstrain takes a different approach: plan-first execution. The agent writes a human-readable plan before touching any files. You review, approve, or reject. Every step is logged with context. No surprises.

And it's fully local if you want. No cloud dependency. No data leaving your machine.

Let's walk through setting up a local coding agent with Ollama.

Step 1: Install Deepstrain 

pip install deepstrain
Enter fullscreen mode Exit fullscreen mode

That's it. It pulls 52 built-in tools for file I/O, git, bash, network, database, and MCP server support.

Step 2: Configure a Local Model

Make sure you have Ollama running with a model pulled. For example:

ollama pull codellama
Enter fullscreen mode Exit fullscreen mode

Then create a config file for Deepstrain:

# ~/.deepstrain/config.yaml
llm:
  provider: ollama
  model: codellama
  base_url: http://localhost:11434
Enter fullscreen mode Exit fullscreen mode

You can also use OpenAI-compatible endpoints (Claude, GPT-4o, DeepSeek) or bring your own API key. Deepstrain is model-agnostic.

Step 3: Run a Task

Let's ask it to refactor a Python file. First, create a messy script:

# messy.py
def calc(a,b):
    c=a+b
    print(c)
    d=a-b
    print(d)
    return c,d
Enter fullscreen mode Exit fullscreen mode

Now run Deepstrain:

deepstrain run "Refactor messy.py: add type hints, proper function names, and docstrings. Keep the same logic."
Enter fullscreen mode Exit fullscreen mode

Step 4: Review the Plan

Deepstrain outputs a plan before executing:

── Plan ──
1. Read messy.py to understand current code
2. Write refactored version with:
   - Type hints (int, int) -> tuple[int, int]
   - Rename calc to add_and_subtract
   - Add docstring
   - Remove inline prints, return values only
3. Write changes to messy.py
4. Verify file content with read tool

Review and approve? (y/n):
Enter fullscreen mode Exit fullscreen mode

You type y and it executes step by step. Each tool call is logged with a stack trace. You can inspect what the agent is thinking at any time.

Step 5: See the Result 

# messy.py (after refactor)
def add_and_subtract(a: int, b: int) -> tuple[int, int]:
    """Calculate sum and difference of two integers.

    Args:
        a: First integer
        b: Second integer

    Returns:
        Tuple containing (sum, difference)
    """
    return a + b, a - b
Enter fullscreen mode Exit fullscreen mode

Clean. No hallucinations because Deepstrain uses deterministic code analysis via its atlas integration when parsing and writing code.

What About Cost?

If you use Ollama, it's free. If you bring your own API key (e.g., DeepSeek), each task costs roughly $0.009. Deepstrain itself is free on PyPI. A Pro license ($9/month) adds HMAC activation and priority support, but the core features work without it.

Trade-offs

  • Deepstrain is terminal-native. No GUI. If you want a clickable IDE plugin, this isn't it.
  • Plan-first execution adds a review step. It's slower than fully autonomous agents, but safer.
  • Local models like CodeLlama are less capable than GPT-4o for complex reasoning. You can swap backends anytime.

Next Steps

Try it with a git repo for automated PR reviews, or wire it into a CI/CD pipeline for safe refactoring. The full feature list — 19 capability domains (security, verification, cloud, infra, math, media) — is documented at massiron.com/deepstrain.

Repository: github.com/mete-dotcom/deepstrain

Top comments (0)