DEV Community: massiron

Code Analysis Without Hallucinations: Using Code Atlas for Deterministic AST Parsing

massiron — Mon, 08 Jun 2026 14:39:46 +0000

If you've ever asked an AI to find all references to a function in your codebase, only to get back a fictional method name or a path that doesn't exist, you know the pain of hallucinated code analysis. LLMs are great for summarization and generation, but they're terrible at deterministic tasks like symbol resolution or dependency graph extraction.

Enter Code Atlas (atlas). It's a deterministic, offline code intelligence engine that works purely on AST parsing — no LLM, no cloud, no hallucinations. You install it with pip, point it at a directory, and get instant, reproducible results.

Step 1: Install

pip install code-atlas

That's it. No Docker, no server setup, no API keys. It runs fully offline.

Step 2: Index your codebase

Navigate to your project root and run:

atlas index

This parses all supported files (Python, JavaScript, TypeScript, Go, Rust, Java, and more) into an AST-based index stored locally. The index is deterministic — same code always produces the same index.

Step 3: Search for symbols

Find every definition and reference to a function or class:

atlas search "parse_config"

Output includes file paths, line numbers, and the symbol type (function, class, variable). No guesswork.

Step 4: Trace dependencies

Visualize import relationships and detect circular dependencies:

atlas graph --format mermaid

This prints a dependency graph in Mermaid format, which you can render in your docs or CI pipeline. It's excellent for impact analysis before a refactor.

Step 5: Run code quality metrics

atlas metrics --risk

Outputs complexity scores, coupling metrics, and risk predictions for each module. This is useful in CI/CD to flag high-risk changes before merging.

Step 6: Integrate with AI agents (optional)

If you use AI coding assistants, atlas can serve as a ground-truth layer via its MCP server:

atlas mcp

Any MCP-compatible agent can now query atlas for real symbol locations, references, and dependency info — eliminating hallucinations from the AI's code analysis.

Limitations to be honest about

Atlas is a CLI tool, not a GUI. If you want a visual code explorer, you'll need to pipe output into something else.
The free tier covers basic search and symbol lookup. Pro features like risk scoring and deep dependency graphs require a $12/month subscription.
It doesn't understand dynamic code patterns (e.g., getattr() in Python) — AST parsing has limits.

When to use Code Atlas

In CI/CD pipelines where you need deterministic quality gates
When refactoring large codebases and need to find all usages of a deprecated API
For AI agent workflows that require factual code context alongside LLM reasoning
Any time you want code analysis that is 100% reproducible and privacy-safe

Try it yourself:

pip install code-atlas
atlas index
atlas search "your_function_name"

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

Building an Auditable AI Agent in Your Terminal with deepstrain

massiron — Mon, 08 Jun 2026 14:39:37 +0000

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

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"

Or with DeepSeek:

export DEEPSTRAIN_MODEL="deepseek:deepseek-chat"
export DEEPSEEK_API_KEY="sk-your-key"

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

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."

deepstrain will:

Generate a plan (and pause for your approval)
Execute the plan step-by-step
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

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)

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

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

Building Controllable AI Agents: Why I Stopped Using Black-Box Tool-Spammers

massiron — Mon, 08 Jun 2026 14:08:37 +0000

The Problem with Most AI Coding Agents

If you've tried AutoGPT, CrewAI, or similar agent frameworks, you've probably seen this: the agent starts spamming tools in random order, writes files without telling you, and when something breaks — it just retries silently. Debugging becomes impossible because there's no trace of what the agent was thinking.

I ran into this wall while automating PR reviews for an open-source project. The agent would attempt a git merge, fail, then try something else — and I'd only find out after a CI failure. I needed controllable, auditable execution, not a black box.

Enter Deepstrain

Deepstrain is a terminal-native AI execution substrate. It's model-agnostic (works with Ollama, Claude, GPT-4o, DeepSeek, any OpenAI-compatible backend), antifragile, and built around plan-first execution. Before touching any files, the agent writes a plan you can review and approve.

Here's a real example: I wanted to refactor a Python module — rename a function, update all call sites, and run tests. With Deepstrain, I ran:

deepstrain run "Rename `calculate_total` to `compute_sum` in src/ and update all usages. Run tests after."

Deepstrain first printed a plan:

Plan:
1. Read src/calculator.py to find `calculate_total` definition
2. Read tests/test_calculator.py to find usages
3. Use `sed` to rename in both files
4. Run `pytest tests/` to verify

I reviewed it, hit 'y', and watched each step execute with full logging. Every command, every file read/write, every error — logged with stack trace. When a test failed because I forgot a second import, the error was captured, the agent adjusted, and I could see exactly what changed.

Key Features That Matter

52 built-in tools: file I/O, git, bash, network, database, MCP server — all sandboxed and logged
Deterministic code analysis via atlas integration: no hallucinations in code understanding, because it uses actual AST parsing
Inspectable cognition: every decision is logged with context. You can replay the entire session
Antifragile: rotating error logs, graceful degradation. If a tool fails, the agent doesn't crash — it reports and retries with a different approach
Model-agnostic: run with Ollama locally (free, no data leaves your machine) or bring your own API key (e.g., DeepSeek at ~$0.009/task)

Trade-offs (Being Honest)

Terminal-native: no GUI. If you prefer a visual interface, this isn't for you.
Learning curve: the plan-first workflow takes getting used to. You can't just fire-and-forget.
Pro license: $9/month for HMAC activation and priority support. The free mode gives read-only tools (file reading, git log, etc.) — useful for auditing but not for writing code.

Where It Shines

CI/CD pipelines: run automated refactoring with full audit trails
PR review automation: read diffs, suggest changes, run tests — all logged
Open-source maintenance: bulk rename, migrate imports, generate test stubs
Local-first development: pair with Ollama for a completely offline AI assistant

Getting Started

pip install deepstrain

Then grab a trial key from the repo or run with a local model:

deepstrain --model ollama:codellama run "Explain the architecture of this project"

No cloud dependency. No vendor lock-in. Just a terminal, a model, and a plan.

Deepstrain is open-source (MIT license) on GitHub. Pro features are $9/month. More details at massiron.com/deepstrain.

Running a Local AI Engineering Agent with deepstrain: A Step-by-Step Tutorial

massiron — Mon, 08 Jun 2026 14:08:33 +0000

If you've ever wanted an AI agent that can read your codebase, run git commands, and execute bash scripts—all without sending a single byte to the cloud—deepstrain is worth a look. It's a local agent runner that connects to any OpenAI-compatible LLM (Ollama, LM Studio, GPT-4o, Claude) and gives you 52 built-in tools. The key difference from other agents: it plans first, then acts. You see the step-by-step reasoning before any tool runs.

Here's how to get it running in five minutes.

1. Install

pip install deepstrain

That's it. No Docker, no API keys, no cloud setup. The package pulls in dependencies for file I/O, git, bash, web fetching, and code analysis via atlas.

2. Configure an LLM Backend

deepstrain needs an LLM behind it. If you have Ollama running locally with a model like codellama or deepseek-coder, create a config file:

# config.yaml
model:
  provider: ollama
  model_name: codellama:7b
  base_url: http://localhost:11434/v1
  temperature: 0.2

For LM Studio, point to its local server:

model:
  provider: openai-compatible
  model_name: local-model
  base_url: http://localhost:1234/v1
  api_key: not-needed

Or use a cloud API (still fully local execution, just the LLM call goes out):

model:
  provider: openai
  model_name: gpt-4o
  api_key: sk-...

Save this as deepstrain.yml in your project root. If you skip it, deepstrain will prompt you interactively.

3. Run Your First Task

Let's ask it to summarize the git log of the current repo:

deepstrain "Show me a summary of the last 5 commits, grouped by author"

Before any tool runs, you'll see the plan printed to stdout. Something like:

[Plan]
1. Run `git log --oneline -5` to get recent commits
2. Parse the output by author
3. Print grouped summary

Then it executes step by step. Each tool call is logged with input, output, and duration.

4. See the Crash-Proof Logging

If a tool fails (e.g., network timeout on a web fetch), deepstrain doesn't crash silently. It writes a rotating log to ~/.deepstrain/logs/ with full context:

2025-03-20 14:32:01 | ERROR | web_fetch | https://example.com/api
  Tool: web_fetch
  Args: {"url": "https://example.com/api", "timeout": 10}
  Error: ConnectionError("Connection refused")
  Plan step: 2 of 5

You get a friendly message in the terminal: "Web fetch failed. Retrying once..." If it fails again, the agent reports the error and asks if you want to continue.

5. Try a Real Refactoring Task with atlas

One of the 52 tools is code_analysis which uses atlas for deterministic code intelligence. Let's say you want to rename a function across a Python project:

deepstrain "Find all callers of function `parse_config` in src/ and rename it to `load_config`"

The agent will:

Use code_analysis to build a call graph
List all files with references
Use file_read and file_write to make changes
Run git diff to show you the diff before applying

You approve each change interactively.

6. Activation and Pricing

deepstrain uses HMAC-SHA256 licensing with edge revocation. After install, you get a free trial. For Pro ($9/mo), you get unlimited tools, priority support, and offline activation. If you bring your own DeepSeek API key, each task costs about $0.009.

Activate with:

deepstrain --activate YOUR_LICENSE_KEY

Once activated, it works fully offline—no phone-home required.

Why Not Just Use Ollama or LangChain?

Raw Ollama gives you a chat interface, not an agent with 52 tools and retry logic.
LangChain requires wiring up chains, memory, and error handling yourself.
deepstrain is pip install and a single command. Zero boilerplate.

Next Steps

Repo: https://massiron.com/deepstrain
Site with full docs: https://massiron.com/deepstrain
Try it on a small codebase first—you can always see the plan before it touches your files.

Feedback welcome. If you hit an edge case, the logs will tell you exactly what happened.

Install: pip install deepstrain

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

Site: https://massiron.com/deepstrain

The Agent OS: Why We Need an Execution Runtime, Not Another Chatbot

massiron — Mon, 08 Jun 2026 14:03:28 +0000

We’re entering the third era of AI. First came chatbots — GPT-3, Claude, Llama. You type, it replies. Useful for drafting emails and brainstorming. Then came copilots — GitHub Copilot, Cursor, Claude Code. They edit code inline, but they’re tethered to a single vendor or model, and they’re still suggestion engines at heart.

Era 3 is the agent runtime. Instead of asking an AI to "suggest a refactor," you tell it to "refactor this module, run the tests, and commit if they pass." That’s a task, not a suggestion. It needs file I/O, git, bash, network calls — and it needs to do them deterministically, auditably, and safely.

That’s where deepstrain comes in. It’s an AI execution substrate: model-agnostic, antifragile, and terminal-native. You install it with pip install deepstrain, point it at any OpenAI-compatible model (Ollama, Claude, GPT-4o, DeepSeek), and get 52 built-in tools: file I/O, git, bash, network, database, MCP server. It runs fully offline with local models — no data leaves your machine.

What makes it different from black-box agents like AutoGPT or CrewAI? Plan-first execution. Before deepstrain touches a single file, it writes a human-reviewable plan. You see every step, approve or reject, and inspect the full decision log with stack traces. No silent crashes — rotating error logs ensure graceful degradation.

For code analysis, deepstrain integrates atlas for deterministic parsing — no hallucinations in understanding your codebase. It supports 19 capability domains: security scanning, cloud provisioning, infra management, math, media processing, and more.

Pricing? Free mode gives you read-only tools (lint, search, analyze). Pro license is $9/month for HMAC activation and priority support. Bring your own API key — tasks cost ~$0.009 with DeepSeek, or free with Ollama.

This isn’t another chatbot wrapper. It’s the OS layer for autonomous engineering. Plan-first, local-first, model-agnostic.

pip install deepstrain

Install: pip install deepstrain
Repo: https://github.com/mete-dotcom/deepstrain
Site: https://massiron.com/deepstrain

Deepstrain: An AI Execution Substrate That Replaces Black-Box Agents With Controllable Engineering Runtimes

massiron — Mon, 08 Jun 2026 14:03:16 +0000

The Problem

AI coding assistants are everywhere, but most of them share a fundamental flaw: they're black boxes. You give them a prompt, they start spamming tools, and you have no idea what they're about to do until it's done — or worse, until they've already made a mess.

Claude Code locks you into Anthropic. Cursor locks you into their backend. GitHub Copilot can't touch your file system. AutoGPT and CrewAI act first, plan never.

If you're building production software, this is unacceptable. You need visibility. You need control. You need to know what your agent is thinking before it touches a single file.

What Deepstrain Is

Deepstrain is a terminal-native AI execution substrate. Think of it as an operating system for AI agents — model-agnostic, antifragile, and built for engineers who refuse to surrender their workflow to a black box.

It runs on top of any OpenAI-compatible model: Ollama (local, free), Claude, GPT-4o, DeepSeek, or your own custom backend. You bring the model, deepstrain provides the runtime.

Concrete Example: Automated PR Review

Here's a real use case. You're an open-source maintainer. Someone submits a PR. You want an AI to review it, but you don't want it hallucinating issues or making changes without your approval.

With deepstrain, you set up a plan-first execution:

# Install
pip install deepstrain

# Run with a local Ollama model
deepstrain run --model ollama:codellama --plan-only "Review PR #42: check for security issues, verify tests pass, suggest refactoring"

Deepstrain writes a plan first — a human-readable list of steps it intends to take. You review it. If it looks good, you approve:

deepstrain approve --task-id abc123

Then it executes. Every tool call is logged with a stack trace and context. If a tool fails, it degrades gracefully — no silent crashes, no hidden errors.

Key Features That Matter

52 built-in tools — file I/O, git, bash, network, database queries, MCP server integration. You're not limited to a curated set of actions.

Deterministic code analysis — via atlas integration, deepstrain doesn't guess about your code. It reads the AST, resolves symbols, and produces factual results. No hallucinations in code analysis.

Portable capabilities — 19 domains including security scanning, verification, cloud operations, infrastructure management, math, and media processing. You can compose these into custom workflows.

Inspectable cognition — every decision the model makes is logged. You can replay the entire reasoning chain after the fact. This is critical for debugging and auditing.

Antifragile by design — rotating error logs, graceful degradation when a tool fails, and never a silent crash. If something goes wrong, you know exactly what and why.

Pricing and Trade-offs

Deepstrain is free to install from PyPI. You can start immediately with a trial key. The Pro license is $9/month for HMAC activation and priority support.

If you bring your own API key (DeepSeek, for example), each task costs roughly $0.009. If you use Ollama locally, it's completely free — no data leaves your machine.

Honest limitations:

The plan-first workflow adds a step. If you want a fire-and-forget agent, this isn't it.
Local models like CodeLlama are slower than cloud models. That's the trade-off for privacy and zero data exfiltration.
The tool ecosystem is 52 tools strong, but it's not infinite. If you need something exotic, you might need to extend it via MCP.

Why This Matters

The era of black-box AI agents is ending. Engineers are demanding transparency, control, and the ability to run models on their own infrastructure. Deepstrain is the runtime layer that makes this possible.

pip install deepstrain

Try it with Ollama first — no cost, no data leaving your machine, and full inspectability from the first command.

Install: pip install deepstrain
Repo: https://github.com/mete-dotcom/deepstrain
Site: https://massiron.com/deepstrain

Building Controllable AI Agents: Why I Stopped Using Black-Box Tool-Spammers

massiron — Mon, 08 Jun 2026 14:03:00 +0000

The Problem with Most AI Coding Agents

Enter Deepstrain

Here's a real example: I wanted to refactor a Python module — rename a function, update all call sites, and run tests. With Deepstrain, I ran:

deepstrain run "Rename `calculate_total` to `compute_sum` in src/ and update all usages. Run tests after."

Deepstrain first printed a plan:

Plan:
1. Read src/calculator.py to find `calculate_total` definition
2. Read tests/test_calculator.py to find usages
3. Use `sed` to rename in both files
4. Run `pytest tests/` to verify

Key Features That Matter

52 built-in tools: file I/O, git, bash, network, database, MCP server — all sandboxed and logged
Deterministic code analysis via atlas integration: no hallucinations in code understanding, because it uses actual AST parsing
Inspectable cognition: every decision is logged with context. You can replay the entire session
Antifragile: rotating error logs, graceful degradation. If a tool fails, the agent doesn't crash — it reports and retries with a different approach
Model-agnostic: run with Ollama locally (free, no data leaves your machine) or bring your own API key (e.g., DeepSeek at ~$0.009/task)

Trade-offs (Being Honest)

Terminal-native: no GUI. If you prefer a visual interface, this isn't for you.
Learning curve: the plan-first workflow takes getting used to. You can't just fire-and-forget.
Pro license: $9/month for HMAC activation and priority support. The free mode gives read-only tools (file reading, git log, etc.) — useful for auditing but not for writing code.

Where It Shines

CI/CD pipelines: run automated refactoring with full audit trails
PR review automation: read diffs, suggest changes, run tests — all logged
Open-source maintenance: bulk rename, migrate imports, generate test stubs
Local-first development: pair with Ollama for a completely offline AI assistant

Getting Started

pip install deepstrain

Then grab a trial key from the repo or run with a local model:

deepstrain --model ollama:codellama run "Explain the architecture of this project"

No cloud dependency. No vendor lock-in. Just a terminal, a model, and a plan.

Deepstrain is open-source (MIT license) on GitHub. Pro features are $9/month. More details at massiron.com/deepstrain.

Install: pip install deepstrain
Repo: https://github.com/mete-dotcom/deepstrain
Site: https://massiron.com/deepstrain

I Built a Terminal-Native AI Agent That Plans Before Acting — Here's Why It Matters

massiron — Mon, 08 Jun 2026 14:02:59 +0000

The Problem with Black-Box Agents

Last month, I watched an AI agent delete a production database migration file. No warning. No audit trail. The agent just... decided it wasn't needed. That's when I realized: most AI coding tools are black boxes. You feed them a prompt, they start spamming tools, and you pray they don't break things.

Deepstrain is my attempt to fix this. It's an open-source, terminal-native AI execution substrate that runs on any model — Ollama, Claude, GPT-4o, DeepSeek, anything OpenAI-compatible. The core idea: plan first, execute second, log everything.

How It Works

Install it:

pip install deepstrain

Configure a backend (Ollama is free, local, and private):

deepstrain config set backend ollama
deepstrain config set model llama3.2:latest

Then give it a task. Instead of silently running commands, Deepstrain first generates a plan:

$ deepstrain run "Refactor the authentication module to use JWT instead of session cookies"

── Planning ──
1. Read auth.py to understand current session-based logic
2. Identify all route handlers that use request.session
3. Create a new jwt_utils.py with encode/decode helpers
4. Update auth.py to import and use jwt_utils
5. Write unit tests for the new JWT flow
6. Run existing tests to verify no regressions

── Review Plan? (y/n) ──

You review the plan. You approve it. Then it executes, step by step, with every command logged to a rotating error file. If something fails, it degrades gracefully — no silent crashes.

What Makes It Different

Model-agnostic: Run it with GPT-4o, Claude, or a local Llama model via Ollama. No vendor lock-in.
52 built-in tools: File I/O, git, bash, network, database queries, MCP server — all accessible from the terminal.
Deterministic code analysis: Atlas integration means no hallucinations when analyzing code structure. It reads the AST, not the model's memory.
Inspectable cognition: Every decision is logged with a stack trace and context. You can replay any session.
Antifragile: Rotating error logs, graceful degradation, never silent crashes. If a tool fails, it retries or asks for input.

Real Use Case: Bulk Refactoring

I used Deepstrain to migrate a 50-file Flask app from template inheritance to a component-based structure. Here's the command:

deepstrain run "Convert all Jinja2 templates to use component includes instead of block inheritance" --read-only-first

The --read-only-first flag runs the entire plan in read-only mode first. No files are touched until I explicitly approve the execution. It generated a 14-step plan, I reviewed it in 2 minutes, approved it, and watched it refactor 50 files in 30 seconds with zero errors.

Limitations (Honest Ones)

It's terminal-native. No GUI, no VS Code extension (yet). You need to be comfortable with a command line.
The plan-first flow adds friction. For simple tasks like "what's the weather?", it's overkill. But for code changes, that friction saves you from disasters.
The Pro license ($9/month) is required for HMAC activation and priority support. The free tier gives you read-only tools and a trial key — enough to evaluate everything.

Who Is This For?

Solo developers who want AI assistance without sending code to third-party servers
Engineering teams that need auditable AI agents for CI/CD pipelines
Open-source maintainers automating PR reviews and test generation
Anyone tired of black-box agents that act without permission

Try It

pip install deepstrain

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

Bring your own API key (DeepSeek costs ~$0.009/task) or use Ollama for free. No data leaves your machine.

Install: pip install deepstrain
Repo: https://github.com/mete-dotcom/deepstrain
Site: https://massiron.com/deepstrain

Running a Local AI Engineering Agent with deepstrain: A Step-by-Step Tutorial

massiron — Mon, 08 Jun 2026 08:32:37 +0000

Here's how to get it running in five minutes.

1. Install

pip install deepstrain

That's it. No Docker, no API keys, no cloud setup. The package pulls in dependencies for file I/O, git, bash, web fetching, and code analysis via atlas.

2. Configure an LLM Backend

deepstrain needs an LLM behind it. If you have Ollama running locally with a model like codellama or deepseek-coder, create a config file:

# config.yaml
model:
  provider: ollama
  model_name: codellama:7b
  base_url: http://localhost:11434/v1
  temperature: 0.2

For LM Studio, point to its local server:

model:
  provider: openai-compatible
  model_name: local-model
  base_url: http://localhost:1234/v1
  api_key: not-needed

Or use a cloud API (still fully local execution, just the LLM call goes out):

model:
  provider: openai
  model_name: gpt-4o
  api_key: sk-...

Save this as deepstrain.yml in your project root. If you skip it, deepstrain will prompt you interactively.

3. Run Your First Task

Let's ask it to summarize the git log of the current repo:

deepstrain "Show me a summary of the last 5 commits, grouped by author"

Before any tool runs, you'll see the plan printed to stdout. Something like:

[Plan]
1. Run `git log --oneline -5` to get recent commits
2. Parse the output by author
3. Print grouped summary

Then it executes step by step. Each tool call is logged with input, output, and duration.

4. See the Crash-Proof Logging

If a tool fails (e.g., network timeout on a web fetch), deepstrain doesn't crash silently. It writes a rotating log to ~/.deepstrain/logs/ with full context:

2025-03-20 14:32:01 | ERROR | web_fetch | https://example.com/api
  Tool: web_fetch
  Args: {"url": "https://example.com/api", "timeout": 10}
  Error: ConnectionError("Connection refused")
  Plan step: 2 of 5

You get a friendly message in the terminal: "Web fetch failed. Retrying once..." If it fails again, the agent reports the error and asks if you want to continue.

5. Try a Real Refactoring Task with atlas

One of the 52 tools is code_analysis which uses atlas for deterministic code intelligence. Let's say you want to rename a function across a Python project:

deepstrain "Find all callers of function `parse_config` in src/ and rename it to `load_config`"

The agent will:

Use code_analysis to build a call graph
List all files with references
Use file_read and file_write to make changes
Run git diff to show you the diff before applying

You approve each change interactively.

6. Activation and Pricing

Activate with:

deepstrain --activate YOUR_LICENSE_KEY

Once activated, it works fully offline—no phone-home required.

Why Not Just Use Ollama or LangChain?

Raw Ollama gives you a chat interface, not an agent with 52 tools and retry logic.
LangChain requires wiring up chains, memory, and error handling yourself.
deepstrain is pip install and a single command. Zero boilerplate.

Next Steps

Repo: https://github.com/mete-dotcom/deepstrain
Site with full docs: https://massiron.com/deepstrain
Try it on a small codebase first—you can always see the plan before it touches your files.

Feedback welcome. If you hit an edge case, the logs will tell you exactly what happened.