Hugging Face's logo

aogavrilov
/
diffusiongemma-agent-iq3-cuda13

Text Generation
GGUF
diffusiongemma-agent
diffusiongemma
coding-agent
cuda
wsl
conversational
Model card Files
xet
 Community
diffusiongemma-agent-iq3-cuda13 / payload /app /docs /dg_agent_cli.md
aogavrilov's picture
aogavrilov
Add files using upload-large-folder tool
ef2127a verified
preview code
|
Raw
History Blame Contribute Delete
40.4 kB

DG Agent CLI

scripts/dg_agent.sh is the unified entrypoint for the local agent stack. It does not replace the open-source tools; it routes to the existing Aider, AgentAPI, and OpenCode wrappers and provides one readiness check.

OSS wrapper map: docs/oss_agent_wrappers.md.

Doctor 

cd /root/diffusiongemma-agent
scripts/dg_agent.sh doctor
scripts/dg_agent.sh doctor --json
scripts/dg_agent.sh status
scripts/dg_agent.sh up
scripts/dg_agent.sh wrappers
scripts/dg_agent.sh wrappers --json
scripts/dg_agent.sh bootstrap
scripts/dg_agent.sh client-pack
scripts/dg_agent.sh client-init --repo /path/to/repo --client cursor
scripts/dg_agent.sh client-report --repo /path/to/repo --client cursor --live
scripts/dg_agent.sh agent-commands --repo /path/to/repo --target all
scripts/dg_agent.sh codex-profile --repo /path/to/repo --target all
scripts/dg_agent.sh agent-bridge --repo /path/to/repo --server opencode-acp
scripts/dg_agent.sh agent-bridge --repo /path/to/repo --server openhands-acp
scripts/dg_agent.sh openhands-mcp -- --repo /path/to/repo --reset
scripts/dg_agent.sh qwen-code -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh autogen -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh smolagents -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh langgraph -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh crewai -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh open-interpreter -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh llamaindex -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh haystack -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh workspace-init --repo /path/to/repo
scripts/dg_agent.sh repo-map --repo /path/to/repo --map-tokens 512
scripts/dg_agent.sh ast-grep --repo /path/to/repo --lang python --pattern 'return $X' --json
scripts/dg_agent.sh code-outline --repo /path/to/repo --lang python --json
scripts/dg_agent.sh agent --repo /path/to/repo --task "..." --mode auto
scripts/dg_agent.sh agent --repo /path/to/repo --task "Read file app.py" --mode read
scripts/dg_agent.sh agent --repo /path/to/repo --task "Fix app.py" --mode edit --file app.py
scripts/dg_agent.sh agent-runs list
scripts/dg_agent.sh agent-runs artifact transcript --latest
scripts/dg_agent.sh tool-loop --repo /path/to/repo --task "..." --out runlogs/tool-loop/latest.json
scripts/dg_agent.sh preflight --repo /path/to/repo
scripts/dg_agent.sh run --repo /path/to/repo --task "..." --file path --start
scripts/dg_agent.sh mcp --list-tools
scripts/dg_agent.sh serena-mcp --help-local
scripts/dg_agent.sh goose-mcp -- info -v
scripts/dg_agent.sh goose-acp -- --help
scripts/dg_agent.sh goose-serve -- --host 127.0.0.1 --port 3294
scripts/dg_agent.sh openhands-acp -- --help
scripts/dg_agent.sh openhands-mcp -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh qwen-code -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh autogen -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh smolagents -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh langgraph -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh crewai -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh open-interpreter -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh llamaindex -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh haystack -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh capabilities
scripts/dg_agent.sh capabilities --live

Checks:

  • backend on 127.0.0.1:4100
  • safe agent gateway / Aider-compatible proxy on 127.0.0.1:8090
  • Aider install
  • AgentAPI install and running state
  • OpenCode and local Node install
  • Goose install
  • LiteLLM gateway install
  • Serena semantic MCP install
  • wrapper/smoke script presence

Bootstrap checks local OSS-wrapper installs and can reinstall missing wrappers:

scripts/dg_agent.sh bootstrap
scripts/dg_agent.sh bootstrap --json
scripts/dg_agent.sh bootstrap --install
scripts/dg_agent.sh bootstrap --external
scripts/dg_agent.sh bootstrap --only openhands,mini-swe-agent --install
scripts/dg_agent.sh bootstrap --smoke-static

By default, bootstrap audits the already recommended core wrappers. Pass --external to include optional OpenHands/SWE-family CLI wrappers. External installers are isolated under repo-local .tools/ or .venv-* paths and are not required for the default reliable agent/session/task path.

Client pack exports endpoint and launch profiles for external clients:

scripts/dg_agent.sh client-pack
scripts/dg_agent.sh client-pack --json
scripts/dg_agent.sh client-pack --env
scripts/dg_agent.sh client-pack --write
scripts/dg_agent.sh client-init --repo /path/to/repo --client cursor
scripts/dg_agent.sh client-smoke --repo /path/to/repo --client cursor --live
scripts/dg_agent.sh client-report --repo /path/to/repo --client cursor --live
scripts/dg_agent.sh agent-commands --repo /path/to/repo --target all
scripts/dg_agent.sh codex-profile --repo /path/to/repo --target all
scripts/dg_agent.sh agent-bridge --repo /path/to/repo --server opencode-acp
scripts/dg_agent.sh agent-bridge --repo /path/to/repo --server openhands-acp
scripts/dg_agent.sh mcp-client-config --repo /path/to/repo --client cursor
scripts/dg_agent.sh mcp-client-config --repo /path/to/repo --client cursor --with-serena
scripts/dg_agent.sh mcp-client-config --repo /path/to/repo --client cursor --with-oss-stack
scripts/dg_agent.sh agent-rules --repo /path/to/repo --target all

The safe gateway exposes OpenAI-compatible discovery endpoints:

http://127.0.0.1:8090/v1/model_card
http://127.0.0.1:8090/v1/capabilities
http://127.0.0.1:8090/v1/agent/routes
http://127.0.0.1:8090/v1/agent/session
http://127.0.0.1:8090/v1/agent/tool
http://127.0.0.1:8090/v1/agent/context
http://127.0.0.1:8090/v1/agent/rag
http://127.0.0.1:8090/v1/agent/sessions
http://127.0.0.1:8090/v1/agent/sessions/latest
http://127.0.0.1:8090/v1/agent/sessions/latest/diff
http://127.0.0.1:8090/v1/agent/sessions/latest/artifacts/{artifact}
http://127.0.0.1:8090/v1/agent/runs
http://127.0.0.1:8090/v1/agent/runs/latest
http://127.0.0.1:8090/v1/agent/runs/latest/artifacts/{artifact}
http://127.0.0.1:8090/v1/agent/tool_manifest
http://127.0.0.1:8090/.well-known/agent.json

Use these when an external OSS agent needs to discover the recommended local route, model limits, tool-call delegation behavior, or MCP resources without opening .dg-agent files directly. The tool manifest includes copy-ready OpenAI Chat Completions and Responses API tool schemas for safe execute_command delegation through dg_agent.sh session. It also includes DG-specific OpenAI function tools for clients that can call tools but cannot mount MCP:

dg_repo_status
dg_git_diff
dg_list_files
dg_read_file
dg_search
dg_repo_pack
dg_repo_map
dg_ast_grep
dg_code_outline
dg_agent
dg_session
dg_context
dg_rag_context
dg_session_artifact
dg_agent_run_artifact

The repo tools are fixed read-only git/rg/file-read operations for clients without MCP. The OSS repo tools delegate to Repomix, Aider repo-map, and ast-grep/code-outline. dg_agent is the high-level HTTP facade over scripts/dg_agent.sh agent --mode auto/read/edit. dg_context and dg_rag_context are read-only; dg_session defaults to dry-run unless HTTP execution is explicitly enabled; dg_session_artifact reads preserved session outputs such as final_diff, context_md, stdout, and stderr; dg_agent_run_artifact reads preserved high-level agent run reports and tool-loop transcripts from runlogs/dg-agent-runs/. /v1/agent/tool executes those DG-specific tool calls and returns a ready role=tool response payload for the next OpenAI-compatible turn. It accepts either {name, arguments} or a full OpenAI tool_call object. Arbitrary execute_command shell execution is blocked there; use repo tools for read-only navigation and dg_session for bounded repo changes. /v1/agent/session returns a dry-run session command by default; real HTTP execution requires DG_AIDER_PROXY_ENABLE_AGENT_EXEC=1 and execute=true. /v1/agent/context and /v1/agent/rag are read-only HTTP versions of dg_agent.sh context and dg_agent.sh rag --print-context; use them when a client has no MCP support but still needs bounded repo context before deciding what to edit. The RAG endpoint is retrieve-only and does not call the model. /v1/agent/sessions* is read-only and exposes preserved session artifacts for HTTP-only clients that cannot mount the DG MCP resources. Artifact names match the CLI names below, including context_md, plan, task_report, verify_report, final_diff, stdout, and stderr. /v1/agent/runs* is the matching read-only surface for high-level scripts/dg_agent.sh agent runs. Artifact names include agent_json, transcript, stdout, and stderr. The same artifacts are available from the CLI through scripts/dg_agent.sh agent-runs list, agent-runs show --latest, and agent-runs artifact transcript --latest. MCP clients get the same surface through dg_agent_runs, dg_agent_run_artifact, dg://agent-runs, dg://agent-runs/latest, and dg://agent-runs/latest/transcript.

Use client-init as the highest-level client bootstrap. It runs workspace-init, installs the default DG+Repomix+Serena MCP bundle for the chosen client, and writes the repo instruction files used by Claude/Cursor/VS Code/Copilot-compatible agents.

Use client-smoke as a target-repo readiness gate before connecting an external client. It can prepare the repo through client-init, then validates hub files, MCP config, agent rules, key launchers, and optionally live endpoints with --live.

Use client-report after client-smoke when an IDE, ACP server, or another agent needs a portable handoff. It writes .dg-agent/CLIENT_HANDOFF.md and .dg-agent/client-handoff.json with the ready commands, route map, MCP config, latest capability snapshot, and live endpoint status when --live is set.

Use agent-commands to install a project command layer for existing clients. It keeps generic snippets under .dg-agent/commands/ and installs the Claude Code project skill .claude/skills/dg-local-agent/SKILL.md.

Use agent-bridge when the client speaks ACP and needs a running agent server instead of only MCP tools. It prepares the repo through client-init, then prints or starts an upstream OpenCode ACP, Goose ACP, or OpenHands ACP server over the same local model/tool bundle.

Every workspace-init also writes .dg-agent/AGENT_HUB.md and .dg-agent/agent-hub.json. Open those first when connecting a new external agent; they summarize the recommended route, endpoint, MCP bundle, ACP bridge, and fallback order for the current repo.

The client pack includes OpenAI SDK, Aider, OpenCode, Goose, Continue, Cline/Roo/Kilo, OpenHands, SWE-agent, mini-swe-agent, MCP stdio profiles, Serena semantic MCP, and copy-ready MCP client configs for Claude Code, Claude Desktop, Cursor, and VS Code. The OpenHands/SWE/MCP profiles are copied into .dg-agent/ by workspace-init as experimental heavy-agent entrypoints over the same local LiteLLM gateway.

Use agent-rules to install client instruction files (AGENTS.md, CLAUDE.md, GitHub Copilot, VS Code instructions, and Cursor rules) that tell external clients to use DG MCP repo tools and bounded sessions instead of pasting large repository context.

The Aider profile is exported as .dg-agent/aider.dg-fast.conf.yml with local model settings/metadata copies, so upstream Aider can also be launched directly:

aider --config .dg-agent/aider.dg-fast.conf.yml path/to/file

External OSS-agent launchers:

scripts/dg_agent.sh openhands -- --repo /path/to/repo --task "..." --dry-run
scripts/dg_agent.sh openhands-acp -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh openhands-mcp -- --repo /path/to/repo --reset
scripts/dg_agent.sh qwen-code -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh autogen -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh smolagents -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh langgraph -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh crewai -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh open-interpreter -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh llamaindex -- --repo /path/to/repo --dry-run
scripts/dg_agent.sh swe-agent -- --repo /path/to/repo --task "..." --dry-run
scripts/dg_agent.sh mini-swe-agent -- --repo /path/to/repo --task "..." --dry-run
scripts/dg_agent.sh mini-swe-run --repo /path/to/repo --task "..." --dry-run --json
scripts/dg_agent.sh mini-swe-runs list
scripts/dg_agent.sh mini-swe-runs show --latest
scripts/dg_agent.sh mini-swe-runs artifact report --latest --path-only
scripts/dg_agent.sh goose-mcp -- info -v
scripts/dg_agent.sh goose-acp -- --help
scripts/dg_agent.sh goose-serve -- --help

These wrappers use installed upstream CLIs when present. Without the CLI they print the exact local profile, model, endpoint, and command to run after installation.

The MCP-enabled OpenCode profile mounts dg_agent and repomix. Serena is available through the separate IDE MCP bundle because its cold start exceeds OpenCode's MCP connection budget on this host. The MCP-enabled Goose profile mounts dg_agent and serena.

mini-swe-run uses the upstream mini-SWE CLI but, in the default safe gateway mode, the proxy adapts mini-SWE text actions into a delegated dg_agent.sh session command. This avoids enabling unsafe generic generation while preserving mini-SWE trajectory, stdout/stderr, command and JSON report artifacts.

Workspace init writes repo-local .dg-agent/ profiles:

scripts/dg_agent.sh workspace-init --repo /path/to/repo
scripts/dg_agent.sh workspace-init --repo /path/to/repo --force

For git repositories, .dg-agent/ is added to the repo-local .git/info/exclude. This keeps the launchers available in the workspace without changing the project's tracked .gitignore or making normal agent runs start from a dirty tree.

It also writes repo-local launchers:

.dg-agent/bin/run --task "..." --file path --start
.dg-agent/bin/agent --task "..." --file path
.dg-agent/bin/preflight --task "..." --file path
.dg-agent/bin/capabilities --latest
.dg-agent/bin/doctor
.dg-agent/bin/up
.dg-agent/bin/down
.dg-agent/bin/plan --task "..." --file path --auto-test
.dg-agent/bin/edit --task "..." --file path --auto-test
.dg-agent/bin/task --plan plan.json --rollback-on-failure
.dg-agent/bin/supervisor --task "..." --file path
.dg-agent/bin/web --port 3284
.dg-agent/bin/context --task "..."
.dg-agent/bin/repo-map --map-tokens 512
.dg-agent/bin/ast-grep --lang python --pattern 'return $X' --json
.dg-agent/bin/code-outline --lang python --json
.dg-agent/bin/client-init --client cursor
.dg-agent/bin/client-smoke --client cursor --live
.dg-agent/bin/client-report --client cursor --live
.dg-agent/bin/agent-commands --target all
.dg-agent/bin/codex-profile --target all
.dg-agent/bin/agent-bridge --server opencode-acp
.dg-agent/bin/agent-bridge --server openhands-acp
.dg-agent/bin/hub
.dg-agent/bin/verify --file path
.dg-agent/bin/sessions list
.dg-agent/bin/aider --help-local
.dg-agent/bin/openhands --help-local
.dg-agent/bin/openhands-acp --help-local
.dg-agent/bin/swe-agent --help-local
.dg-agent/bin/mini-swe-agent --help-local
.dg-agent/bin/mini-swe-run --task "..." --dry-run --json
.dg-agent/bin/mini-swe-runs list
.dg-agent/bin/mcp --list-tools
.dg-agent/bin/mcp-http --help-local
.dg-agent/bin/serena-mcp --help-local
.dg-agent/bin/goose-mcp --help-local
.dg-agent/bin/goose-acp --help
.dg-agent/bin/goose-serve --help

Preflight checks a target repo before a live agent run:

scripts/dg_agent.sh preflight --repo /path/to/repo
scripts/dg_agent.sh preflight --repo /path/to/repo --task "..." --file path --json

It reports whether the repo is needs-setup, static-ready, or live-ready. static-ready means the wrapper/repo setup is valid but the backend model is not loaded yet.

One-command run combines workspace init, preflight, optional service startup, and the reliable agent path:

scripts/dg_agent.sh run --repo /path/to/repo --task "..." --file path
scripts/dg_agent.sh run --repo /path/to/repo --task "..." --file path --start
scripts/dg_agent.sh run --repo /path/to/repo --task "..." --file path --dry-run --json

run does not load the model unless --start is passed.

agent is the highest-level local facade:

scripts/dg_agent.sh agent --repo /path/to/repo --task "Find where add(a, b) is implemented" --mode auto
scripts/dg_agent.sh agent --repo /path/to/repo --task "Fix add(a, b)" --mode edit --file calc.py

--mode auto routes inspection tasks to the read-only OpenAI tool-loop and edit tasks to the artifacted session runner. --mode read always uses bounded repo tools and writes runlogs/dg-agent-runs/*/agent.json plus the tool-loop transcript. --mode edit keeps the older session behavior: context, plan, task runner, verification, rollback, and session.json.

tool-loop is the reference OpenAI-compatible tool-calling client. It fetches DG tool schemas from /v1/agent/tool_manifest, calls Chat Completions through LiteLLM, executes returned tool calls through /v1/agent/tool, appends role=tool messages, and can save the full transcript:

scripts/dg_agent.sh tool-loop \
  --repo /path/to/repo \
  --task "Find the implementation of add(a, b)" \
  --out runlogs/tool-loop/latest.json

Use --stop-after-tool when the caller wants only the raw tool transcript. Without it, the proxy turns the final role=tool payload into a deterministic summary response. Use --tool dg_read_file or --read-only to constrain the loop to repo inspection tools when connecting a cautious external agent.

The reliable edit path is intentionally layered. It tries the Aider-compatible OSS wrapper first, then verifies syntax/tests, then applies small deterministic repairs when the model call produced no usable diff but the task states an exact code constraint. It also adds transient .aider.dg-local/ metadata to the target repo's local .git/info/exclude, so repeated runs do not start from a dirty tree. Session reports mark repaired model attempts as aider-with-deterministic-repair.

Capability probes run a small end-to-end audit of the wrapper stack:

scripts/dg_agent.sh capabilities
scripts/dg_agent.sh capabilities --json
scripts/dg_agent.sh capabilities --live --json
scripts/dg_agent.sh capabilities --latest
scripts/dg_agent.sh capabilities --latest --path-only

Without --live, this checks repo-local workspace bootstrapping, every repo-local .dg-agent/bin/* launcher, the installed OSS wrapper matrix, OpenHands/SWE-family profile launchers, the proxy adapter, and exact replace repair without loading the model. With --live, it also runs a real GPU-backed Aider edit where malformed model output is repaired by the proxy and then applied as an Aider diff.

Capability reports are saved under:

runlogs/dg-agent-capabilities/latest.json
runlogs/dg-agent-capabilities/YYYYMMDD-HHMMSS-{static,live}.json

Use --no-save to skip writing these files for a one-off probe.

Short stack commands:

  • status: check backend, proxy and LiteLLM
  • up: ensure backend, proxy and LiteLLM are running
  • down: stop backend, proxy and LiteLLM

Smoke 

scripts/dg_agent.sh smoke
scripts/dg_agent.sh smoke --suite context
scripts/dg_agent.sh smoke --suite auto-test
scripts/dg_agent.sh smoke --suite verify
scripts/dg_agent.sh smoke --suite session
scripts/dg_agent.sh smoke --suite sessions
scripts/dg_agent.sh smoke --suite session-artifacts
scripts/dg_agent.sh smoke --suite agent
scripts/dg_agent.sh smoke --suite capabilities
scripts/dg_agent.sh smoke --suite proxy-adapter
scripts/dg_agent.sh smoke --suite supervisor
scripts/dg_agent.sh smoke --suite wrappers
scripts/dg_agent.sh smoke --suite bootstrap
scripts/dg_agent.sh smoke --suite client-pack
scripts/dg_agent.sh smoke --suite workspace-init
scripts/dg_agent.sh smoke --suite client-init
scripts/dg_agent.sh smoke --suite client-smoke
scripts/dg_agent.sh smoke --suite client-report
scripts/dg_agent.sh smoke --suite agent-commands
scripts/dg_agent.sh smoke --suite codex-profile
scripts/dg_agent.sh smoke --suite ide-clients
scripts/dg_agent.sh smoke --suite agent-bridge
scripts/dg_agent.sh smoke --suite external-agents
scripts/dg_agent.sh smoke --suite mini-swe-runner
scripts/dg_agent.sh smoke --suite preflight
scripts/dg_agent.sh smoke --suite run
scripts/dg_agent.sh smoke --suite task
scripts/dg_agent.sh smoke --suite goose
scripts/dg_agent.sh smoke --suite goose-mcp
scripts/dg_agent.sh smoke --suite goose-acp
scripts/dg_agent.sh smoke --suite openhands-acp
scripts/dg_agent.sh smoke --suite openhands-mcp
scripts/dg_agent.sh smoke --suite qwen-code
scripts/dg_agent.sh smoke --suite autogen
scripts/dg_agent.sh smoke --suite smolagents
scripts/dg_agent.sh smoke --suite langgraph
scripts/dg_agent.sh smoke --suite crewai
scripts/dg_agent.sh smoke --suite open-interpreter
scripts/dg_agent.sh smoke --suite llamaindex
scripts/dg_agent.sh smoke --suite haystack
scripts/dg_agent.sh smoke --suite litellm
scripts/dg_agent.sh smoke --suite gateway-clients
scripts/dg_agent.sh smoke --suite openai-sdk
scripts/dg_agent.sh smoke --suite mcp
scripts/dg_agent.sh smoke --suite mcp-http
scripts/dg_agent.sh smoke --suite serena-mcp
scripts/dg_agent.sh smoke --suite watchdog
scripts/dg_agent.sh smoke --suite stack-control
scripts/dg_agent.sh smoke --suite agentapi --suite opencode-provider

Suites:

  • context: context pack and generated task-runner plan
  • auto-test: automatic verification command inference
  • verify: standalone verification command runner
  • session: full context->plan->task->verify artifacted run
  • sessions: session history listing and inspection
  • session-artifacts: direct retrieval of preserved session artifacts
  • agent: recommended local coding-agent mode
  • capabilities: compact capability harness for workspace launchers, installed OSS wrappers, external-agent profiles, proxy, and live-ready paths
  • proxy-adapter: file-listing normalization and exact repair fallback in the Aider proxy
  • supervisor: rg + Aider/model + verification + deterministic repair fallback
  • wrappers: installed OSS-wrapper matrix and recommended routing
  • bootstrap: audit/install wrapper control path without loading the model
  • client-pack: OpenAI-compatible client/IDE/agent profile export
  • workspace-init: repo-local .dg-agent/ client pack and quickstart files
  • client-init: one-shot workspace + MCP bundle + client rules bootstrap
  • client-smoke: target-repo readiness gate for external IDE/agent clients
  • client-report: portable Markdown/JSON handoff for external clients
  • agent-commands: repo-local command kit and Claude Code project skill
  • codex-profile: project-local Codex CLI config for the DG safe proxy
  • ide-clients: Continue/Cline/Roo/Kilo/OpenAI-compatible repo-local profile snippets
  • agent-bridge: one-shot ACP bridge over OpenCode/Goose/OpenHands OSS agent servers
  • external-agents: OpenHands/SWE/mini-SWE local profile wrappers and launchers
  • mini-swe-runner: artifacted mini-SWE runner dry-run contract
  • preflight: target-repo readiness check before agent execution
  • run: one-command workspace-init -> preflight -> optional start -> agent
  • edit: natural-language dg_agent.sh edit
  • task: multi-step task runner
  • agentapi: AgentAPI over Aider
  • goose: Goose over the local OpenAI-compatible proxy
  • litellm: LiteLLM gateway over the local OpenAI-compatible proxy
  • gateway-clients: checked-in IDE/OpenAI-compatible client profiles
  • openai-sdk: real Python OpenAI SDK chat completion through LiteLLM
  • mcp: MCP stdio server initialize, tools/list, and dg_context tool call
  • watchdog: backend/proxy/LiteLLM watchdog status and ensure
  • stack-control: one-command status, up and ensure aliases
  • opencode-provider: OpenCode provider discovery
  • opencode-run: minimal OpenCode run fallback

Agent Mode

Use run as the default local coding-agent entrypoint:

scripts/dg_agent.sh run \
  --repo /path/to/repo \
  --task "Fix hello.py so greet('Ada') returns exactly hello, Ada!" \
  --file hello.py \
  --start

Use agent directly when workspace/preflight/service startup are already handled:

scripts/dg_agent.sh agent \
  --repo /path/to/repo \
  --task "Fix hello.py so greet('Ada') returns exactly hello, Ada!" \
  --file hello.py

agent is a conservative profile over the artifacted session path. It builds a compact repo context pack, generates a task-runner plan, enables auto-test inference, verifies after the edit, rolls back failed task-runner edits, uses deterministic repair fallbacks for exact small Python edits, and preserves all artifacts under runlogs/dg-agent-sessions/.

Useful options:

  • --file path: repeatable file hints for small-context work
  • --test-cmd "...": explicit verification from the target repo
  • --max-files N: default 3, for bounded repo-RAG context
  • --no-auto-test: disable inferred verification
  • --no-rollback: keep failed edits for inspection
  • --out-dir /path: write session artifacts outside the default runlog

Smoke:

scripts/dg_agent.sh smoke --suite agent

Reliable Edits

Run the full artifacted agent session:

scripts/dg_agent.sh session \
  --repo /path/to/repo \
  --task "Fix hello.py so greet('Ada') returns exactly hello, Ada!" \
  --file hello.py \
  --auto-test \
  --rollback-on-failure

The session writes a directory under runlogs/dg-agent-sessions/ by default:

  • context.md
  • context.json
  • plan.json
  • task-report.json
  • verify.json
  • before.status.txt
  • after.status.txt
  • before.diff
  • final.diff
  • session.json

List and inspect prior sessions:

scripts/dg_agent.sh sessions list
scripts/dg_agent.sh sessions show --latest
scripts/dg_agent.sh sessions show /path/to/session-or-session.json
scripts/dg_agent.sh sessions list --json

Print the latest session diff or a specific preserved artifact:

scripts/dg_agent.sh sessions diff --latest
scripts/dg_agent.sh sessions diff 1
scripts/dg_agent.sh sessions artifact context_md --latest
scripts/dg_agent.sh sessions artifact plan --latest --path-only
scripts/dg_agent.sh sessions artifact stdout --latest --path-only

The same preserved artifacts are available through the safe gateway:

GET http://127.0.0.1:8090/v1/agent/sessions
GET http://127.0.0.1:8090/v1/agent/sessions/latest
GET http://127.0.0.1:8090/v1/agent/sessions/latest/diff
GET http://127.0.0.1:8090/v1/agent/sessions/latest/artifacts/context_md
GET http://127.0.0.1:8090/v1/agent/sessions/{session_id}/artifacts/final_diff

Useful artifact names:

  • context_md
  • context_json
  • plan
  • task_report
  • verify_report
  • before_diff
  • final_diff
  • task_stdout
  • task_stderr

Build a compact repo context pack without calling the model:

scripts/dg_agent.sh context \
  --repo /path/to/repo \
  --task "Find where health response is built" \
  --max-files 3 \
  --out /tmp/dg-context.md

Generate a task-runner plan from a normal task:

scripts/dg_agent.sh plan \
  --repo /path/to/repo \
  --task "Add uptime_ms to the health response" \
  --file server.py \
  --auto-test \
  --out /tmp/dg-plan.json

Natural-language one-step edit without writing a JSON plan:

scripts/dg_agent.sh edit \
  --repo /path/to/repo \
  --task "Fix hello.py so greet('Ada') returns exactly hello, Ada!" \
  --file hello.py \
  --auto-test \
  --rollback-on-failure

This creates a temporary task-runner plan and delegates to scripts/run_task_runner.sh.

--auto-test currently infers conservative commands such as:

  • python3 -m py_compile file.py
  • bash -n file.sh
  • python3 -m json.tool file.json >/dev/null
  • go test ./...
  • cargo test
  • npm test -- --runInBand
  • python3 -m pytest -q

Run the same verification layer directly:

scripts/dg_agent.sh verify \
  --repo /path/to/repo \
  --file server.py \
  --report /tmp/dg-verify.json

or with an explicit command:

scripts/dg_agent.sh verify \
  --repo /path/to/repo \
  --test-cmd "python3 -m pytest -q" \
  --json

Explicit multi-step plan:

scripts/dg_agent.sh task \
  --repo /path/to/repo \
  --plan /path/to/plan.json \
  --report /tmp/dg-task-report.json \
  --rollback-on-failure

This delegates to scripts/run_task_runner.sh.

Web/API Agent 

scripts/dg_agent.sh web --repo /path/to/repo --port 3284

Open:

http://127.0.0.1:3284/chat

This delegates to AgentAPI over Aider.

OpenCode 

scripts/dg_agent.sh opencode-agent -- /path/to/repo
scripts/dg_agent.sh opencode -- /path/to/repo
scripts/dg_agent.sh opencode-mcp -- /path/to/repo
scripts/dg_agent.sh opencode-acp -- --cwd /path/to/repo --hostname 127.0.0.1 --port 3295
scripts/dg_agent.sh agent-bridge --repo /path/to/repo --server opencode-acp --start

For the primary bounded terminal workflow on Windows, use scripts/dg_agent.sh opencode-agent -- /path/to/repo or scripts/run_opencode_agent_windows.ps1 from the target repository. It keeps only OpenCode's Bash tool and routes it through the verified DG read/session delegate. Generic OpenCode/MCP/ACP remain separate OSS integration paths.

OpenCode is available as an experimental TUI, MCP-enabled TUI, and ACP server. The current local package includes the Windows OpenCode payload for PowerShell usage and opencode-linux-x64 for WSL MCP process spawning. Provider/run, ACP, and live MCP smokes pass; opencode mcp list verifies dg_agent, repomix, and serena as connected. For reliable edits, prefer dg_agent.sh task.

Goose Experiment 

scripts/dg_agent.sh goose -- run \
  --no-profile \
  --max-turns 1 \
  --text "Reply exactly OK."

Goose is available as an experimental ready-made OSS agent shell over the same local OpenAI-compatible proxy. It brings sessions, MCP/extensions, review, and TUI commands, but the current local DG profile is not reliable enough at native tool-calling to replace the Aider/task-runner path. Keep --max-turns and an external timeout around non-interactive goose run experiments.

scripts/dg_agent.sh goose-mcp -- ... runs Goose with an isolated Goose HOME and mounts both the local DG MCP SDK server and upstream Serena semantic/LSP MCP as stdio extensions. scripts/dg_agent.sh goose-acp exposes that same profile as a stdio ACP agent server; scripts/dg_agent.sh goose-serve -- --port 3294 exposes Goose's HTTP/WebSocket ACP server.

OpenHands is also available as an ACP stdio server:

scripts/dg_agent.sh openhands-acp -- --help
scripts/dg_agent.sh agent-bridge --repo /path/to/repo --server openhands-acp --start

This route uses openhands acp --override-with-envs under the hood because the standalone openhands-acp entrypoint is not reliable in the current package.

OpenHands can also consume the repo-local MCP stack directly through its own MCP config:

scripts/dg_agent.sh openhands-mcp -- --repo /path/to/repo --reset
.dg-agent/bin/openhands-mcp --reset

This writes .dg-agent/openhands-persistence/mcp.json with diffusiongemma-local-agent, repomix, and serena.

Qwen Code is available on this Windows host as a bounded terminal inspection experiment. The unified entrypoint prefers the WSL runner with DG, Repomix, and Serena MCP mounted; the native Windows launcher remains a read-only fallback on the safe GPU gateway. Edit requests stay on the Aider/session path:

scripts/dg_agent.sh qwen-code -- --repo /path/to/repo --dry-run
.dg-agent/bin/qwen-code --dry-run
python scripts/dg_agent.py qwen-code -- --repo . --dry-run -- --help

Use an explicit file path in the prompt, for example --prompt "Read src/app.py. Summarize the request flow.". See docs/qwen_code_local.md for the current runner and verified behavior.

AutoGen AgentChat is available as a Python framework route:

scripts/dg_agent.sh autogen -- --repo /path/to/repo --dry-run
.dg-agent/bin/autogen --dry-run

It uses autogen-agentchat, autogen-ext[openai], and configs/client_profiles/autogen.dg.json.

Hugging Face smolagents is available as another Python framework route:

scripts/dg_agent.sh smolagents -- --repo /path/to/repo --dry-run
.dg-agent/bin/smolagents --dry-run

It uses smolagents[toolkit], openai, and configs/client_profiles/smolagents.dg.json.

LangGraph/LangChain is available as another Python graph-agent framework route:

scripts/dg_agent.sh langgraph -- --repo /path/to/repo --dry-run
.dg-agent/bin/langgraph --dry-run

It uses langgraph, langchain, langchain-openai, and configs/client_profiles/langgraph.dg.json. The working local route uses WSL Python 3.14 plus Linux cp314 wheels in .wheelhouse/langgraph-wsl-cp314; the Windows venv is not used for imports because Windows App Control blocks pydantic_core.

CrewAI is available as another Python multi-agent framework route:

scripts/dg_agent.sh crewai -- --repo /path/to/repo --dry-run
.dg-agent/bin/crewai --dry-run

It uses crewai.Agent, Task, Crew, LLM, and configs/client_profiles/crewai.dg.json.

Open Interpreter is available as an OSS code-execution shell route:

scripts/dg_agent.sh open-interpreter -- --repo /path/to/repo --dry-run
.dg-agent/bin/open-interpreter --dry-run

It uses open-interpreter with auto_run=false, safe_mode=ask, and configs/client_profiles/open-interpreter.dg.json.

LlamaIndex is available as a RAG/agent workflow framework route:

scripts/dg_agent.sh llamaindex -- --repo /path/to/repo --dry-run
.dg-agent/bin/llamaindex --dry-run

It uses OpenAILike plus AgentWorkflow.from_tools_or_functions, which selects ReActAgent for the current non-function-calling model profile.

Haystack is available as a BM25 RAG pipeline over repository files:

scripts/dg_agent.sh haystack -- --repo /path/to/repo --dry-run
.dg-agent/bin/haystack --dry-run

It uses haystack-ai with InMemoryDocumentStore, InMemoryBM25Retriever, and OpenAIChatGenerator.

Docs: docs/goose_local.md, docs/qwen_code_local.md, docs/autogen_local.md, docs/smolagents_local.md, docs/langgraph_local.md, docs/crewai_local.md, docs/open_interpreter_local.md, docs/llamaindex_local.md, docs/haystack_local.md.

LiteLLM Gateway 

scripts/dg_agent.sh litellm

Then point OpenAI-compatible clients at:

base_url: http://127.0.0.1:4100/v1
api_key: dummy
model: diffusiongemma-local

This is the preferred compatibility endpoint for external IDE clients and agent shells. It routes to the local Aider-compatible proxy and keeps a stable model alias in configs/litellm.dg.yaml.

In safe mode, generic chat still avoids raw backend generation. If a client sends a command-like OpenAI tools schema, the proxy returns a tool_calls response that delegates to dg_agent.sh session --rollback-on-failure. The same delegate is available through non-streaming POST /v1/responses as a Responses API function_call output item.

Docs: docs/litellm_gateway.md.

Client profiles for Continue, Cline/Roo/Kilo style OpenAI-compatible clients, and OpenAI SDK scripts are in configs/client_profiles/.

RAG Context 

scripts/dg_agent.sh rag --repo /repo --task "..." --print-context
scripts/dg_agent.sh rag --repo /repo --task "..." --max-context-chars 650 --max-files 3 --max-tokens 128
scripts/dg_agent.sh repo-pack --repo /repo --include "src/**" --style markdown --stdout

This wraps scripts/rag_code_agent.py, the read-only rg retrieval layer for small-context use. Use --print-context when an outer agent should inspect the selected file map and snippets before planning edits.

repo-pack wraps upstream Repomix through local npx --yes repomix. Use tight --include filters, --compress, and --token-budget when the client needs a packed artifact rather than ranked snippets.

For MCP-capable clients, configs/client_profiles/mcp-client-snippets.json also includes optional native Repomix MCP server snippets using scripts/run_repomix_mcp.sh. The wrapper pins the local Node path before launching upstream repomix --mcp, which is more reliable from IDE-launched MCP processes than calling npx directly.

Docs: docs/rag_agent.md.

MCP Server 

scripts/dg_agent.sh mcp --list-tools
scripts/dg_agent.sh mcp
scripts/dg_agent.sh mcp-http -- --host 127.0.0.1 --port 8765
scripts/dg_agent.sh serena-mcp --help-local

The MCP server is a local stdio bridge for clients that can launch MCP tools. The default implementation uses the official modelcontextprotocol/python-sdk FastMCP server; --legacy keeps the dependency-free JSON-RPC fallback for debugging. It exposes reliable DG wrapper commands as tools instead of asking the model to invent tool calls:

mcp-http exposes the same tools over the official streamable HTTP transport at http://127.0.0.1:8765/mcp for clients that cannot spawn stdio servers.

serena-mcp is an optional upstream semantic/LSP MCP server. Its active WSL runtime is currently available; client-init includes it only after the live serena-mcp --check-installed probe succeeds. The core DG MCP server remains available independently.

  • dg_repo_status
  • dg_list_files
  • dg_search
  • dg_read_file
  • dg_git_diff
  • dg_task_note
  • dg_task_notes
  • dg_status
  • dg_context
  • dg_rag_context
  • dg_rag_answer
  • dg_repo_pack
  • dg_preflight
  • dg_plan
  • dg_task
  • dg_session
  • dg_verify
  • dg_capabilities
  • dg_client_smoke
  • dg_client_report
  • dg_sessions
  • dg_session_artifact

It also exposes resources dg://client-pack, dg://status, dg://usage, dg://sessions, dg://sessions/latest, dg://sessions/latest/diff, dg://capabilities/latest, dg://client-handoff, and dg://client-handoff/markdown; repo-local handoff resources dg://agent-hub, dg://agent-hub/markdown, dg://command-kit, dg://command-kit/markdown, dg://ide-clients, dg://ide-clients/markdown, dg://codex-profile, and dg://codex-profile/config; and prompts dg_agent_session, dg_agent_context, dg_agent_continue_latest for MCP clients that support prompt/resource discovery.

Use dg_client_report first when an MCP client needs a portable repo handoff, then read dg://client-handoff or dg://client-handoff/markdown. For a broader bootstrap, read dg://agent-hub/markdown, then use the command, IDE, or Codex resources matching the external client. Use dg_rag_context for compact repository-scale retrieval without model generation, or dg_repo_pack for bounded Repomix packed context. Use dg_session for one-shot bounded edits. Use dg_preflight, dg_context, dg_plan, and dg_task when an MCP client should inspect or persist a task plan before execution.

Use configs/client_profiles/mcp-server.json or the workspace-local .dg-agent/mcp-server.json profile in MCP-capable clients. Copy-ready client templates are exported as .dg-agent/claude-code.mcp.json, .dg-agent/claude-desktop-mcp.json, .dg-agent/cursor.mcp.json, .dg-agent/vscode.mcp.json, and .dg-agent/mcp-client-snippets.json.

Use scripts/dg_agent.sh mcp-client-config --repo /path/to/repo --client cursor or .dg-agent/bin/mcp-client-config --client cursor to merge the local server entry into project client configs without removing unrelated MCP servers. Add --with-repomix to install the optional native Repomix MCP server in the same config. Add --with-serena to install the optional native Serena MCP server; the flags can be combined. Use --with-oss-stack for the recommended full bundle: DG workflow tools, Repomix repository packing, and Serena semantic/LSP tools.

Docs: docs/mcp_server.md.

Docs: docs/ide_client_profiles.md.

Watchdog 

scripts/dg_agent.sh status
scripts/dg_agent.sh up
scripts/dg_agent.sh watchdog -- status
scripts/dg_agent.sh watchdog -- ensure
scripts/dg_agent.sh watchdog -- watch --interval 30 --restart

Docs: docs/stack_watchdog.md.

Windows 

powershell -ExecutionPolicy Bypass -File \\wsl.localhost\Ubuntu-24.04\root\diffusiongemma-agent\scripts\dg_agent_windows.ps1 doctor