GerdsenAI Agentic Devtools

A cross-platform agentic toolkit: Markdown-to-PDF document creation, deep research intelligence, adversarial red-team review, autonomous sprint execution, vector DB management, and a project scaffolder — usable from Claude, Codex, Copilot, VS Code, Cursor, Gemini CLI, and OpenCode via MCP + AGENTS.md, with local inference over Ollama, vLLM, and LM Studio.

It runs natively in Claude Code via /gerdsenai: slash commands and is powered by the GerdsenAI Document Builder.

Formerly the "GerdsenAI Markdown-to-PDF Suite." The /gerdsenai: command namespace, settings, and install paths are unchanged — upgrading is seamless.

Table of Contents

• Quick start
• Commands
• Use from any AI tool
• Local inference
• Configuration
• Design-driven planning
• Documentation
• About Gerdsen.AI
• License
• Disclaimer

Quick start

Prerequisite: uv. The plugin is uv-native — uv creates the virtual environment and provisions a suitable Python (3.9+) itself, so a separate Python install is not required. On Windows, also install Git for Windows (provides Git Bash).

# Install uv (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

Install the plugin — either point Claude Code at a local checkout:

claude --plugin-dir .

…or add the marketplace from inside Claude Code: run /plugin, open Marketplaces, add GerdsenAI/GerdsenAI-Agentic-Devtools, then install gerdsenai from Discover and run /reload-plugins.

…or from the terminal:

claude plugin marketplace add GerdsenAI/GerdsenAI-Agentic-Devtools
claude plugin install gerdsenai@gerdsenai-agentic-devtools-marketplace --scope user
# later, to update: claude plugin marketplace update gerdsenai-agentic-devtools-marketplace && claude plugin update gerdsenai@gerdsenai-agentic-devtools-marketplace

Configure and build:

/gerdsenai:setup            # guided install + preferences (output, logos, page size, vector DB)
/gerdsenai:build my-doc.md  # build a professional PDF

See docs/USAGE.md for full install methods, troubleshooting, and detailed configuration.

Commands

Command	Description
/gerdsenai:help [command]	A quick read-only tour — what every command does, your current config state, and where to start
/gerdsenai:setup	Install, configure, or update the Document Builder
/gerdsenai:config [show|get|set]	View and set any plugin setting from one schema — grouped, validated, in-place (surfaces every key, including the previously hand-edit-only ones)
/gerdsenai:build <target>	Build PDFs — single file or recursive directory (auto-detected)
/gerdsenai:research-report [topic|file]	Deep multi-source research and intelligence reports; source-freshness monitoring when given a report file
/gerdsenai:red-team <target>	Adversarial analysis across 11 domains (code, security, deps, architecture, testing, DevOps, DB, AI/ML, accessibility, docs, strategic)
/gerdsenai:vector-db [operation]	Vector DB management: report, store, query, sync, configure — ChromaDB, Pinecone, or Qdrant (local FastEmbed or server/Cloud). Detect-and-reuse onboarding, project-aware model recommendation, local-LLM embeddings, dual-backend auto-mirror, and local↔cloud sync
/gerdsenai:sprint-execute [plan|description|resume]	Autonomous sprint executor: Socratic planning, autocoding, auto-commit
/gerdsenai:llm [detect|configure|test|run]	Configure or use a local/remote OpenAI-compatible LLM backend
/gerdsenai:init [target-dir]	Scaffold a new cross-platform, agent-ready project (AGENTS.md, MCP, CLAUDE.md, local-inference config, git init)
/gerdsenai:agentic-ui <target-dir> [--style observability|chatgpt|manus]	Scaffold a standalone agent UI: observability (live terminal → pseudo-desktop → computer-use, --phase 1|2|3), chatgpt (a ChatGPT-style chat UI), or manus (a Manus-style agent workspace: chat + live Plan / Artifacts / Activity). Public-safe, localhost+token, BYO-model
/gerdsenai:discover [goal]	Discover Claude Code plugins, skills, features, and modes that fit your goal — ranked suggestions with exact install commands. Never auto-installs
/gerdsenai:design-plan	Print a curated starter prompt for /ultraplan (cloud planning, browser review) so a design refresh of the plugin's customer surface is driven by Anthropic's frontend-design skill
/gerdsenai:dashboard	Launch the optional local dashboard — a read-only web UI to watch this plugin's own agents work (live activity stream + sprint/to-do board). Localhost + token, opt-in
/gerdsenai:session [status|sync|use|serve|build …]	GerdsenAI Session: discover/sync your AI providers (Ollama/Claude/OpenAI/Gemini/vLLM/LM Studio/OpenRouter) + vector stores (Qdrant/Chroma/Pinecone) and serve a redacted config to the Session workspace over a local 127.0.0.1:4318 bridge. build scaffolds the read-only workspace — an AI provider/vector tab plus a multi-session rail + chat/plan/tool-call timeline that observes running agents (with a per-session model chip). Local-first, loopback+token, secrets stay in your keychain

/gerdsenai:agentic-ui generates a standalone Node + Docker Compose app (not a UI for this plugin) in three cumulative phases: a live in-browser terminal (xterm.js + node-pty), a Dockerized pseudo-desktop (Xvfb + x11vnc + noVNC), and a computer-use loop (screenshot → VLM → click/type). It is public-safe and BYO-model — it ships no credentials or hardcoded endpoints, binds 127.0.0.1 behind a generated auth token, and defaults to read-only; you supply your own vision model.

A pdf-document-authoring skill activates automatically when you write Markdown intended for PDF, guiding front matter, heading hierarchy, code blocks, and Mermaid diagrams. Full command options, agent workflows, and report types are documented in docs/USAGE.md.

Skip the questions. Any command that asks a clarifying question accepts --yes (alias -y) to take the documented defaults and proceed (--force implies it where it already means overwrite); questions also auto-skip when your intent is explicit. For safety, --yes alone never auto-confirms an install or an overwrite of existing files. See docs/USAGE.md.

Watch the plugin work (optional dashboard)

/gerdsenai:dashboard builds and optionally starts an optional local read-only web UI scoped to this plugin — distinct from the AgenticUI scaffolder (which generates standalone apps for any AI agent). The frontend is a Next.js 16 + shadcn app (shadcn here is Base-UI-based, not Radix) shipped as source and built once to a static export (npm install && npm run build), then served by a zero-dependency pure-Node server.js (node server.js). It's an agentic-observability UI — it turns raw tool events into plain-language narration ("red-team is running a shell command"), infers live presence (ticking timers, a breathing status dot), and is honest about every inference (inferred elements are visibly marked). Two views:

• Mission Control — the multi-project Fleet: read-only git status across your registered projects (branch, ahead/behind "as of last fetch", dirty counts, last commit, a per-repo 60s activity sparkline), plus a live global narration feed. Manage which repos are watched with /gerdsenai:dashboard add|remove|list <path> (writes ~/.gerdsenai/projects.json).
• Project Cockpit — one project up close: a plan spine, a live "now playing" lane (with a Workflow fan-out visualization), a scrubbable Replay timeline, a tool-call inspector, an attention center, and the sprint/to-do board (from CLAUDE.md + todo files).

The activity stream that powers the narration is opt-in (dashboard_activity_log: on; off by default). It binds 127.0.0.1, requires a generated auth token (embedded in the URL), and is read-only — every git call is allow-listed (rev-parse/status/rev-list/log only, via execFile, no shell, no network), registered paths are realpath-clamped, and the registry is mutated only out-of-band via the CLI. Ahead/behind reflect your last local git fetch. Node.js is required to run it. See docs/USAGE.md for configuration and security details.

Use from any AI tool

The toolkit is not Claude-only. It ships an MCP server and an AGENTS.md so the same capabilities are available to Codex, GitHub Copilot, VS Code, Cursor, Gemini CLI, OpenCode, and other agents. Your host agent does the reasoning; the repo provides portable scripts that wrap the PDF renderer, vector memory, source tracking, and local-inference layer.

• MCP server exposes seven tools: build_pdf, vector_db_query, vector_db_store, vector_db_report, vector_db_sync, track_sources, and llm_complete.
• AGENTS.md is read natively by Codex, Cursor, Gemini CLI, and OpenCode; a Copilot instructions file covers GitHub Copilot.

See docs/CROSS-PLATFORM.md for the full client matrix and registration steps.

Local inference

AI features can route to any OpenAI-compatible /v1 endpoint, so models served locally work without a hosted API. Backends (Ollama, vLLM, LM Studio) are auto-detected.

/gerdsenai:llm detect   # probe running backends

See docs/LOCAL-INFERENCE.md for backends, configuration, and environment variables.

Configuration

After /gerdsenai:setup, settings are stored either per-repo at .claude/gerdsenai.local.md or globally at ~/.claude/gerdsenai.global.md (you choose the scope; a per-repo file takes precedence). Key fields cover the Document Builder path, vector DB mode, output location, logos, page size, and citation style.

View or change any setting with /gerdsenai:config (show for a grouped, described list of every key; set <key> <value> for a schema-validated, in-place edit), or run the /gerdsenai:setup wizard. The authoritative schema is scripts/lib/settings-schema.json, and a copyable template ships at templates/gerdsenai.settings.example.md. The full reference and Document Builder config.yaml styling options are in docs/USAGE.md.

Secrets (API keys: PINECONE_API_KEY, QDRANT_API_KEY, OPENAI_API_KEY, GERDSEN_LLM_API_KEY, GERDSEN_EMBED_API_KEY, plus the Session AI-tab provider keys ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY read by the gerdsen provider-sync CLI) are never stored in the settings file. Set them as environment variables, or configure them once via the plugin's config (/plugin → this plugin) — declared in userConfig, they're masked on entry and stored in your OS keychain, then exposed to the plugin's scripts automatically.

Design-driven planning

For releases that are primarily about how the plugin looks and feels (templates, scaffolder copy, README, marketplace listing), use /gerdsenai:design-plan to print a curated starter prompt and paste it into Claude Code's /ultraplan (research preview; v2.1.91+) — the planning task moves to a cloud Claude Code session that you review in your browser (inline comments, emoji approvals, structured outline). This repo's .claude/settings.json enables Anthropic's frontend-design plugin per-repo so the cloud session inherits its bold aesthetic POV (typography, color, motion, composition — explicitly anti-"AI slop"). Install it once on your machine with claude plugin install frontend-design. Approve the plan in the browser, then execute the design refresh locally on a feat/* branch. Full workflow: skills/agentic-ui/references/design-ultraplan.md.

Note on auto-enabled plugin. Cloning this repo and opening it in Claude Code (or running /ultraplan against it) auto-enables frontend-design@claude-plugins-official via the committed .claude/settings.json. The marketplace is Anthropic-owned (anthropics/claude-plugins-official); the plugin contributes a single design skill and no commands/hooks/MCP servers. If you don't want this, delete the entry from .claude/settings.json before the first session — it's the only enabled plugin in that file. Any PR adding entries to that file is owner-reviewed (see .github/CODEOWNERS).

Documentation

• docs/USAGE.md — install methods, command options, agent workflows, configuration reference, troubleshooting
• docs/CROSS-PLATFORM.md — using the toolkit from any AI tool (MCP + AGENTS.md)
• docs/LOCAL-INFERENCE.md — Ollama / vLLM / LM Studio configuration
• docs/OPTIMIZATION.md — performance and resource tuning
• CHANGELOG.md — release history

About Gerdsen.AI

GerdsenAI Agentic Devtools is built and maintained by Gerdsen.AI, which designs practical, cross-platform tooling that helps teams put AI agents to work — from document generation to research, code review, and autonomous engineering. Learn more at gerdsen.ai.

License

MIT License — see LICENSE.

Disclaimer

This software is provided "AS IS", without warranty of any kind. AI-generated output (documents, research, code, reviews) may be inaccurate or incomplete — always verify before relying on it. Nothing produced by this toolkit constitutes legal, financial, or other professional advice, and you are responsible for the content you generate and how you use it. See DISCLAIMER.md for full terms.