deepstrain 1.1.2

Terminal-native AI engineering agent - 59 tools, 19 capability domains, DAG orchestration, DeepSeek powered

deepstrain

Terminal-native AI engineering assistant. 57 tools, 19 capability domains, topology-aware DAG orchestration, IMAP email, DeepSeek powered.

Bring your own key. Your code never leaves your machine. Works offline after first activation.

pip install deepstrain
deepstrain          # first run: guided setup → straight into chat

That's it. deepstrain detects the first run, walks you through getting a free DeepSeek API key, validates it, does a live handshake with the model, then drops you into the agent.

---

Table of Contents

• What Is deepstrain
• Installation
• First Run Experience
• Configuration
• Settings GUI
• License Activation
• CLI Reference
• Agent Tools — All 57
• Topology-Aware Orchestration
• Session Features
• Automation & Scripting
• Architecture

---

What Is deepstrain

deepstrain is a pip-installable AI agent that runs entirely in your terminal. It connects directly to the DeepSeek API using your own key — no proxy, no data collection, no hidden cloud. The model has access to 57 built-in tools: it can read and write files, analyse entire projects, run git commands, execute tests, spawn parallel sub-agents, read your email via IMAP, execute multi-step DAG pipelines across 19 capability domains — all with your explicit permission.

Property	Value
Runtime	Local-only — your data never leaves your machine
Model	DeepSeek Chat / R1 via your own API key
Install	pip install deepstrain
Tools	57 built-in + 19 capability domains
Orchestration	Topology-aware DAG engine with event-sourced state
Languages	English (default) · Türkçe
Price	$9/mo monthly · $6/mo annual

---

Installation

Windows

pip install deepstrain --user
deepstrain        # guided first-run setup

Linux / macOS

pip install deepstrain --user
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
deepstrain        # guided first-run setup

From Source (dev)

git clone https://github.com/mete-dotcom/deepstrain.git
cd deepstrain
pip install -e .

---

First Run Experience

When you run deepstrain for the first time (no config file found), it shows a welcoming setup guide:

  ┌──────────────────────────────────────────────────────────────┐
  │    d e e p  S T R A I N   — just installed ✓               │
  │    terminal-native AI engineering assistant                  │
  │    57 tools  ·  19 capability domains  ·  DeepSeek powered  ·  your data stays local  │
  └──────────────────────────────────────────────────────────────┘

  To get started you need a FREE DeepSeek API key:
    1.  Go to  →  platform.deepseek.com/api_keys
    2.  Sign up (free) and create a key
    3.  Paste it below — it stays on your machine only

  Your API key: ••••••••••••••••••••••••••••••••••••
  ✓  Connected  ·  $5.00 USD

  deepstrain: Ready! I'm your terminal-native AI engineering
  assistant...

The key is validated against the DeepSeek API immediately. After a successful key, the model sends its own greeting, and the chat session opens automatically.

---

Configuration

Config is stored at ~/.deepstrain/config.toml.

# ~/.deepstrain/config.toml
[default]
api_key      = "sk-..."          # your DeepSeek API key
model        = "deepstrain"      # deepstrain · deepstrain-r1 · deepseek-chat · deepseek-reasoner
theme        = "green"           # green · blue · purple · amber · arctic · matrix · mono
sounds       = "true"            # true · false
sound_volume = "soft"            # soft · standart · yüksek
language     = "en"              # en · tr
budget_limit = "0"               # monthly USD cap (0 = unlimited)

Environment variable override:

export DEEPSEEK_API_KEY="sk-..."   # takes precedence over config file

Model aliases:

Alias	Maps to
deepstrain	deepseek-chat (default)
deepstrain-r1	deepseek-reasoner (step-by-step reasoning)

---

Settings GUI

deepstrain settings

Opens a graphical panel (tkinter) where you can configure everything visually: API key, model, terminal theme (7 colour swatches with live preview), sounds, language, monthly budget, and license status.

---

License Activation

deepstrain activate DSTR-XXXXX-XXXXX-XXXXX-XXXXX
deepstrain status       # show tier, expiry, grace period
deepstrain deactivate   # remove license (for machine transfer)

Get a key: deepstrain.vercel.app

Grace period: Expired licenses have a 7-day grace period before lockout.

---

CLI Reference

deepstrain                    # smart entry: first-run setup or direct chat
deepstrain <command> [args]

Command	Description
chat	Start interactive AI agent session
resume	Pick a recent session and continue it
logs	List recent session logs (newest first)
eval 'task'	One-shot AI task — run agent on a prompt and exit
exec <tool>	Run a single tool directly and print result
serve	Start HTTP API server (POST /exec, POST /eval)
configure	Set API key and model interactively
settings	Graphical settings panel (tkinter)
why	Why DeepSeek + why deepstrain? Terminal handshake
hello	Onboarding wizard
init	Create default ~/.deepstrain/config.toml
activate KEY	Activate with a license key
deactivate	Remove local license token
status	Show license status (tier, expiry, grace)
doctor	Full health check (config, license, git, workers)
version	Show version

eval flags

deepstrain eval "task" --loop --max-iter 5 --max-turns 20 --json

---

Agent Tools — All 57

Once inside deepstrain chat, the AI picks the right tool for each step automatically. The capability tool unlocks 18 specialised domains — use it when no dedicated tool fits. The execute_multi tool chains multiple capabilities into a DAG with automatic dependency resolution and parallel execution.

File Reading

Tool	What it does
read_file	Read a file, optional line range
chunk_read	Read large files in 80-line chunks
file_outline	Fast structure view: class/def/import lines
surgical_read	Extract ONLY the target function/class — 95% token savings

File Writing & Editing

Tool	What it does
write_file	Write (overwrite) a file
patch_file	Surgical text replacement — auto syntax-check + rollback for .py
smart_patch	patch_file with fuzzy fallback (difflib ≥72%)
surgical_patch	AST-based symbol replacement — finds by name, auto-adjusts indentation, validates syntax

Navigation & Search

Tool	What it does
list_dir	List files and folders
find_files	Find by glob pattern
search_in_files	Regex search across Python files
grep_files	Regex search across any file type
find_definition	Find where a function/class is defined
find_usages	Find all call sites
verify_symbol	Quick existence check

Code Analysis

Tool	What it does
find_symbols	List all def/class in a file (AST, zero-token)
detect_duplicates	Find copy-paste code blocks
read_patterns	Extract code conventions
interface_check	Find missing methods between abstract class and implementation
dead_code	Find defined-but-never-used functions and classes
circular_deps	Detect circular import cycles
import_graph	Show what a file imports, or who imports it
detect_stack	Auto-detect tech stack
schema_check	Compare migration SQL vs schema

Composite Analysis

Tool	What it does
project_context	~1500-token project snapshot
project_summary	Directory tree with file/line counts
strain_project	Single-pass composite: stack + map + style + circular deps + dead code

Execution & Git

Tool	What it does
run_command	Run a shell command (timeout, dangerous pattern blocking, permission required)
run_tests	Run pytest
git_diff	Show unstaged or staged changes
git_log	Show recent commits
git_commit	Stage all + commit with message

Memory

Tool	What it does
remember / recall	Session RAM key-value store
save_note / read_notes	Persistent global notes
save_project_note / read_project_notes	Per-project notes
audit_md_notes	Scan and analyse markdown notes

Planning & Control

Tool	What it does
make_plan	Display a numbered plan before multi-step edits
checkpoint	Log a progress milestone
ask_user	Pause and ask a clarifying question
grant_permission / list_permissions	Session permission management

Plugins & Workers

Tool	What it does
plugin_tool	Run a custom plugin from agent_tools/
worker	Run a worker function from agent_workers.py

Sub-Agents

Tool	What it does
list_agent_types	List available specialist roles
delegate	Delegate a task to a read-only specialist sub-agent
spawn_agents	Run multiple tasks in parallel sub-agents
link_project	Register an external project by alias
cross_project	Send a read-only task to a linked project

Built-in roles: analyst, security, performance, test, docs, refactor

Capability Domains (single tool — 18 domains)

Tool	What it does
capability	Run an operation in any of 18 specialised domains

18 domains: browser, cloud, config, database, document, execution, filesystem, git, governance, infra, math, media, network, nlp, notification, package, security, verification

DAG Orchestration

Tool	What it does
execute_multi	Execute multiple capability operations as a DAG. Automatic dependency resolution, parallel execution, trust-based rerouting on failure, timeout enforcement, retry with backoff

---

Topology-Aware Orchestration

deepstrain includes a built-in topology-aware DAG orchestration engine that sits between the agent and the capability domains as the central runtime authority.

How it works

                      ┌──────────────────────────┐
                      │     FermionKernel         │
                      │   (central runtime auth)  │
                      │                           │
  Agent ──tasks──▶   │  DagEngine                 │
                      │  ├─ build_graph()          │
                      │  ├─ resolve_order()        │
                      │  ├─ execute_level()  ◀─ async TaskGroup
                      │  ├─ handle_failure()  ◀─ trust-based reroute
                      │  └─ compensate()           │
                      │                           │
                      │  PolicyEngine · Guard     │
                      │  RuntimeState · TrustStore │
                      └──────────────────────────┘
                               │
                    ┌──────────┼──────────┐
                    ▼          ▼          ▼
              Capability  Capability  Capability
              Node (DAG)  Node (DAG)  Node (DAG)

Key design decisions

Principle	Detail
Immutable nodes	CapabilityNode is fully frozen — all state lives in the event-sourced RuntimeState
Deterministic order	Execution order is determined solely by dependency topology + runtime state, not by trust scores
Trust → rerouting	Trust scores influence rerouting, fallback, and risk evaluation — never scheduling order
Event sourcing	All state changes are append-only NodeEvents. Same events → same state, every time
Async by default	Parallel levels execute via asyncio.TaskGroup. Horizontal scalability from the start
Timeout	Every node has a configurable timeout enforced by asyncio.wait_for
Retry with backoff	Exponential backoff on transient failures. Circuit breaker prevents cascading

Execution flow

1. Build graph — execute_multi receives tasks with dependency declarations
2. Topological sort — Kahn's algorithm produces parallel-safe execution levels
3. Level-by-level execution — each level runs concurrently via TaskGroup
4. Failure handling — failed nodes trigger trust-based rerouting to alternate domains
5. Event recording — every state transition is recorded as an immutable event

Example: CI pipeline as DAG

# Inside chat, tell deepstrain:
"run security scan, then run tests in parallel with linting,
then deploy if both pass"

The agent calls execute_multi with:

{
  "tasks": [
    {"node_id": "scan",  "domain": "security",     "operation": "sast_scan"},
    {"node_id": "lint",  "domain": "verification", "operation": "ruff_check", "deps": ["scan"]},
    {"node_id": "test",  "domain": "verification", "operation": "pytest",     "deps": ["scan"]},
    {"node_id": "deploy","domain": "cloud",        "operation": "vercel_deploy", "deps": ["lint", "test"]}
  ]
}

This executes as:

• Level 0: scan (alone)
• Level 1: lint + test (parallel — both depend on scan)
• Level 2: deploy (depends on both lint and test)

If scan fails, lint and test are blocked. The rerouter checks trust scores and may fall back to an alternate security tool.

---

Session Features

Permission system

Every write/execute operation triggers a permission prompt:

  [permission]  deepstrain → dosya yaz: src/auth.py
  [y] yes   [n] no   [always] always allow   [never] never allow  → 

Session logging

deepstrain logs      # list recent sessions
deepstrain resume    # interactive picker → continue where you left off

Project notes

deepstrain writes DEEPSTRAIN_NOTES.md inside your project. Next session: notes are auto-injected into context.

Budget tracking

Set a monthly USD cap. At 80%: warning. At 100%: asks whether to continue.

Themes

7 colour themes: green (default), blue, purple, amber, arctic, matrix, mono.

Sounds

Permission requests and completed tasks play brief notification tones.

---

Automation & Scripting

One-shot task

deepstrain eval "audit src/ for security issues"

CI repair loop

deepstrain eval "run tests and fix any failures" --loop --max-iter 5

Pre-commit hook

# .git/hooks/pre-commit
STAGED=$(git diff --cached --name-only --diff-filter=AM | grep "\.py$")
if [ -n "$STAGED" ]; then
  deepstrain eval "security audit: $STAGED"
fi

HTTP API server

deepstrain serve --port 8765

# Single tool
curl -X POST http://localhost:8765/exec \
  -H "Content-Type: application/json" \
  -d '{"tool": "read_file", "args": {"path": "src/main.py"}}'

# Agent eval
curl -X POST http://localhost:8765/eval \
  -H "Content-Type: application/json" \
  -d '{"prompt": "find all TODO comments", "max_turns": 8}'

Shortcut prefixes

review auth.py, debug TypeError, plan add JWT, docs UserService,
test _parse_token, refactor database.py, security api/routes.py

---

Architecture

deepstrain/
├── __init__.py              exports chat_loop, __version__
├── chat.py                  agent loop, 57 tools, 19 capability domains,
│                            permission system, session logging, budget tracking
├── cli.py                   argparse entry points, first-run flow, settings GUI
├── i18n.py                  EN/TR string table
├── config.py                load_config()
├── license.py               license mask/activate helpers
├── verify.py                offline license verification
│
├── orchestration/           ★ NEW: topology-aware DAG orchestration
│   ├── __init__.py          module root, get_kernel() singleton
│   ├── kernel.py            FermionKernel (central runtime authority)
│   ├── engine.py            DagEngine (async, TaskGroup-based execution)
│   ├── graph.py             CapabilityNode, GraphTopology (topo sort,
│   │                        cycle detection, critical path)
│   ├── state.py             RuntimeState (event-sourced, SQLite persistence)
│   ├── events.py            NodeEvent, EventStream (transition validation)
│   └── trust.py             TrustWeight, WeightedRerouter
│
├── capability/              18 domain implementations
│   ├── notification.py      email, Slack, Discord, webhook, push, SMS
│   ├── nlp.py               summarization, sentiment, entities, classification
│   ├── math.py              sympy evaluate/simplify/solve/diff/integrate
│   ├── media.py             Pillow resize/convert, ffmpeg transcode, OCR
│   ├── document.py          Markdown→HTML/PDF, DOCX, spreadsheet
│   ├── network.py           HTTP, ping, DNS, TCP, traceroute
│   ├── config.py            TOML/YAML/JSON/INI read/write/validate
│   ├── database.py          SQLite queries, migrations, backup/restore
│   ├── security.py          SAST, secret scan, dep audit, SBOM
│   ├── verification.py      pytest, mypy, ruff, coverage, bandit
│   ├── cloud.py             AWS, GCP, Azure, Cloudflare, Vercel, Netlify
│   ├── browser.py           Playwright/Selenium automation
│   ├── execution.py         Shell command execution
│   ├── filesystem.py        File operations
│   ├── git.py               Git operations
│   ├── infra.py             Docker/K8s operations
│   ├── package.py           pip/npm package management
│   └── governance/          Policy enforcement, audit trail
│
├── runtime/                 → backward-compat re-export to orchestration
│
└── tests/
    ├── test_orchestration.py    57 tests (events, graph, state, trust,
    │                             engine, kernel, replay)
    ├── test_runtime_kernel.py   11 backward-compat tests
    ├── test_capability_*.py     domain-specific capability tests
    └── ...

~/.deepstrain/
├── config.toml              user settings
├── notes.md                 persistent global notes
├── budget.json              monthly token spend tracker
└── logs/
    └── YYYYMMDD_HHMMSS.json  one file per session (auto-saved)

How tools work

The agent calls DeepSeek's function-calling API. deepstrain registers 57 tool schemas. DeepSeek picks the right tool(s) for each step. deepstrain executes them locally and returns results. The loop continues until DeepSeek returns a final text answer.

Crash resilience

deepstrain is designed to never show a raw Python traceback:

• _agent_turn() catches every network error and returns a friendly message
• chat_loop() catches unexpected exceptions per turn, logs them, and keeps the session alive
• main() wraps the entire process in a top-level handler

---

Building from Source

git clone https://github.com/mete-dotcom/deepstrain.git
cd deepstrain
pip install build
python -m build
pip install dist/deepstrain-*.whl

---

License

Commercial — requires activation. See deepstrain.vercel.app for pricing.

Free mode (no activation): basic chat without tools.

---

deepstrain v0.7.0