DEV Community

massiron
massiron

Posted on • Originally published at massiron.com

Building an Auditable AI Agent in Your Terminal with deepstrain

#agentic #python #opensource #devtools

Why deepstrain?

Most AI coding agents are black boxes. You give them a prompt, they start spamming tools, and you hope for the best. If something breaks, good luck figuring out why.

deepstrain takes a different approach: plan-first, inspectable execution. Every decision is logged, every plan is reviewed before touching files, and you can run it fully offline with local models.

This tutorial walks through installing deepstrain, configuring it with your preferred model, and running a practical task.

Step 1: Install

deepstrain is a Python package, available via pip:

pip install deepstrain
Enter fullscreen mode Exit fullscreen mode

That’s it. No Docker, no cloud setup, no hidden dependencies. The free tier includes all 52 built-in tools and 19 capability domains.

Step 2: Configure a Model Backend

deepstrain is model-agnostic. You can use:

  • Ollama (free, local)
  • Claude (Anthropic API)
  • GPT-4o (OpenAI API)
  • DeepSeek (cheap, ~$0.009/task)
  • Any OpenAI-compatible endpoint

Set your backend via environment variables. For example, with Ollama:

export DEEPSTRAIN_MODEL="ollama:llama3.1:70b"
export OLLAMA_HOST="http://localhost:11434"
Enter fullscreen mode Exit fullscreen mode

Or with DeepSeek:

export DEEPSTRAIN_MODEL="deepseek:deepseek-chat"
export DEEPSEEK_API_KEY="sk-your-key"
Enter fullscreen mode Exit fullscreen mode

If you have a local model running, deepstrain works fully offline — zero data leaves your machine.

Step 3: Run Your First Task

Let’s ask deepstrain to refactor a Python file. Create a messy script:

# messy.py
def a(x,y):return x+y
def b(x,y):return x*y
def c(x,y):return x-y
Enter fullscreen mode Exit fullscreen mode

Now run:

deepstrain run "Refactor messy.py: rename functions to descriptive names, add type hints, and write a docstring for each. Show me the plan first."
Enter fullscreen mode Exit fullscreen mode

deepstrain will:

  1. Generate a plan (and pause for your approval)
  2. Execute the plan step-by-step
  3. Log every decision with full context

You’ll see output like:

[PLAN] Step 1: Read messy.py
[PLAN] Step 2: Rename a() -> add()
[PLAN] Step 3: Rename b() -> multiply()
[PLAN] Step 4: Rename c() -> subtract()
[PLAN] Step 5: Add type hints (int, int) -> int
[PLAN] Step 6: Add docstrings
[PLAN] Step 7: Write changes to messy.py

Review plan? (y/n): y

[LOG] Executing step 1...
[LOG] Executing step 2...
...
[DONE] Refactored messy.py
Enter fullscreen mode Exit fullscreen mode

Step 4: Inspect the Logs

Every run creates a timestamped log file in ~/.deepstrain/logs/. Open it to see the full decision trail:

cat ~/.deepstrain/logs/$(ls -t ~/.deepstrain/logs/ | head -1)
Enter fullscreen mode Exit fullscreen mode

You’ll see the exact model responses, tool calls, and stack traces. This is inspectable cognition — no black box.

Step 5: Use Built-in Tools

deepstrain ships with 52 tools across 19 domains. Here’s a quick sample:

  • File I/O: read, write, edit, patch
  • Git: git_status, git_diff, git_commit
  • Bash: run_shell, run_script
  • Network: http_get, http_post
  • Database: sql_query (sqlite, postgres)
  • MCP: mcp_call (connect to MCP servers)

To list all tools:

deepstrain list-tools
Enter fullscreen mode Exit fullscreen mode

Limitations to Know

  • deepstrain is terminal-native — no GUI. It’s designed for developers who live in the terminal.
  • The free tier is fully functional but limited to 100 tasks per day. Pro ($9/mo) removes this limit and adds HMAC activation for team use.
  • Deterministic code analysis (via atlas) only works for Python and JavaScript currently. Other languages fall back to LLM-based analysis.
  • If you use a small local model (e.g., 7B), plan quality may suffer. A 70B+ model or GPT-4o gives best results.

Next Steps

  • Run it on CI: deepstrain works great in GitHub Actions for automated PR reviews or test generation.
  • Use it offline: Pair with Ollama and a local model for air-gapped environments.
  • Extend with MCP: Connect to your own MCP servers for custom capabilities.

Check the repo for examples and advanced config: https://github.com/mete-dotcom/deepstrain

Or just install and try it:

pip install deepstrain
Enter fullscreen mode Exit fullscreen mode

Top comments (1)

Collapse
 
alexshev profile image
Alex Shev •

Auditability is underrated. A terminal agent should leave enough trace that you can answer: what did it read, what did it change, what command proved the result?