What People Use Machina For

Repo Onboarding

As a developer, I want to understand an unfamiliar codebase quickly so I can become productive fast.

"Scan this workspace, tell me what stack it uses, what the key files are, and where I should start."

• Scans the workspace and detects stack clues
• Identifies key files and entry points
• Reads README and config files
• Summarizes architecture hints
• Shows which tools and steps were used

Outcome: The developer understands the project in minutes instead of manually exploring for an hour.

Environment Preparation

As a developer, I want Machina to prepare my project workspace so I can start working without manual setup friction.

"Prepare this project for work."

• Inspects the repo and project structure
• Opens the workspace context
• Runs safe setup commands where allowed
• Surfaces missing dependencies or issues
• Asks for approval before riskier actions

Outcome: Project setup becomes a guided execution flow instead of a manual checklist.

Debug Workflow

As an engineer, I want Machina to help me inspect an issue across code, diagnostics, and repo state.

"Debug this issue in the current workspace."

• Reads diagnostics and searches code semantically
• Checks repo state and diffs
• Runs safe commands
• Chains the investigation as a workflow
• Summarizes likely causes and next actions

Outcome: Debugging becomes structured, inspectable, and faster.

Technical Review

As a tech lead, I want a quick summary of project state and risky areas before reviewing changes.

"Inspect this repo, summarize the current state, and show me risky areas."

• Checks repo contents and status
• Highlights high-risk files or changes
• Exposes runtime steps and events
• Requires approval for any mutating actions

Outcome: Technical review starts with a reliable operational snapshot.

Consultancy Discovery

As a consultant, I want to map a client project quickly and identify the important integration points.

"Map the project, explain the architecture clues, and highlight integration points."

• Scans workspace structure
• Identifies frameworks and languages
• Uses semantic search for concepts
• Stores findings as reusable context

Outcome: Discovery work becomes faster and more repeatable.

Repeatable Workflows

As an engineering team, we want to convert repeated routines into reusable workflows.

"Run the refactor workflow."

• Loads a predefined workflow
• Executes ordered steps with context passing
• Records execution history
• Lets users inspect, retry, or approve steps

Outcome: Operational routines become reusable AI-native workflows.

Multi-Agent Coordination

As a user, I want specialized agents to collaborate on a task without manually orchestrating them.

"Have one agent inspect the repo, another analyze diagnostics, and a third summarize the likely fix path."

• Assigns specialized roles and delegates work
• Shows handoffs and message flow
• Preserves approvals and event trace
• Presents a combined result

Outcome: Complex analysis becomes coordinated and inspectable.

Safe Governed Automation

As a stakeholder, I want to see AI execution without giving the system uncontrolled power.

"Run a gated command in this sandbox."

• Shows the plan before action
• Pauses for approval on gated steps
• Exposes timeline, metrics, and events
• Allows approve / deny / retry / explain

Outcome: The system demonstrates trust, governance, and runtime transparency.

Desktop Technical Companion

As a developer on my machine, I want a local desktop app that gives me a persistent AI shell for project work.

"Open my current workspace and help me continue the last task."

• Launches as a desktop shell and restores context
• Exposes workspace views and runtime state
• Supports local-first operation with no cloud dependency

Outcome: Machina feels like an always-available technical operating layer, not a disposable browser assistant.

Security Audit Workflow

As a security-conscious developer, I want to scan my codebase for vulnerabilities and ensure secrets never leak into logs.

"Run a security scan on this repo and check for hardcoded secrets."

• Runs the built-in security-deep-scan chain template (part of the Security Center)
• Detects SQL injection, XSS, SSRF, command injection, and 10 more patterns with CWE IDs
• Scrubs API keys, JWTs, and connection strings from all outputs before display
• Stores findings in the immutable audit log with SHA-256 hash chain

Outcome: Security review is repeatable, evidence-backed, and leaves no sensitive data exposed in logs or the UI.

Visual Pipeline Design

As a platform engineer, I want to design a multi-agent data pipeline visually and deploy it without writing orchestration code.

"Build a pipeline that scans dependencies, checks for outdated packages, and opens a PR summary."

• Opens Visual Workflow Studio on a blank canvas
• Drags tools from the palette and wires output ports to input ports
• Clicks Auto-Assign to score and assign the best agents per step
• Runs Optimize to detect parallelism opportunities and annotate the graph
• Executes with live per-node debug overlays and streams results back

Outcome: Complex multi-agent pipelines are designed in minutes, not hours, with no YAML or orchestration DSL required.

Step-Through Pipeline Debugging

As an automation engineer, I want to debug a failing chain one step at a time and see exactly where it breaks.

"Open my deploy-readiness chain in the Studio Debugger and step through it."

• Loads the saved chain in the Studio canvas via Open Chain
• Clicks Debug to spin up a server-side debug session
• Uses Step Over to advance one node at a time — amber pulse while running, green ✓ on success, red ✗ on failure
• Inspects per-step duration metrics and tool output in the resizable results tray
• Clicks Continue to drain the remaining steps after the bad one is fixed

Outcome: Pipeline failures become inspectable like a stack trace, not a black box — the failing step is visible on the canvas with its full output.

Composite Audit in One Click

As an engineering lead before a release cut, I want a single button that runs security, dependency, and code-quality audits and produces one consolidated note.

"Run the Master Audit composite chain on this workspace."

• Picks the Master Audit (Composite) template from the Studio Tmpl tab
• The bus auto-instantiates three sub-chains — security-audit, dependency-check, code-quality-scan — and wires their real IDs into the parent
• Click Execute: each sub-chain expands recursively (depth limit 5, cycle detection) into its child steps
• Final step writes a Markdown note under notes/ consolidating all findings
• Each sub-chain can also be re-run, edited, or rolled back independently

Outcome: Reusable audit chains compose into product-grade workflows. The output is a permanent, indexable artifact — not a chat reply.

Inspecting Agent Coordination

As an SRE running a multi-agent task, I want to see exactly which agents talked to each other and why.

"Show me the agent communication graph for the last release-readiness run."

• Opens the Agents → Communications sub-tab
• The SVG graph shows agent nodes connected by color-coded edges — cyan requests, amber negotiations, purple handoffs, emerald broadcasts — each labeled with message counts
• Stats cards summarize total messages, negotiations, pending requests, and active collaborations
• The unified activity feed lists every event chronologically with type filters
• The Threads toggle groups related messages by correlation_id into collapsible cards

Outcome: Multi-agent behavior becomes auditable. You can answer questions like "why did the security agent take over from the git agent?" with one screen.

MCP — Connect Anything, Expose Everything

As a developer using Claude Desktop and Cursor, I want MachinaOS to both consume external MCP tools and expose its own tools to those clients.

"Connect a custom MCP filesystem server, then point Cursor at MachinaOS as an MCP server."

• Opens MCP → Servers and uses Quick Pick to register a curated server in two clicks
• Smart auto-detection fills command, args, and env hints based on package name
• Discovered tools appear namespaced as mcp.<server>.<tool> and are usable from chat, Studio, and chains
• Simultaneously, MachinaOS exposes its native tools, resources, and prompt templates over its own SSE transport at /mcp/serve/sse, behind the same policy gate
• External clients (Claude Desktop, Cursor) connect and call MachinaOS tools as if they were native

Outcome: MachinaOS becomes the central hub of an agent ecosystem — both consuming and providing capabilities through the same open protocol.

Conversational Delegation via Neural Link

As a developer, I want to type my intent in plain English and have MachinaOS pick the right specialist agent and run a verified plan.

"Delegate to security-auditor and scan this project for leaked secrets."

• Types intent in the enhanced Neural Link chat surface
• The planner sees each agent's system prompt and routes the task to the correct specialist (here: delegate_to: agent_security-auditor)
• RAG-augmented context (ChromaDB) injects relevant code snippets into the LLM prompt
• Plan card streams in with per-step tool selection, approval gates for risky operations, and live tool output
• Risky steps pause for explicit human approval before execution

Outcome: Natural language becomes the primary control surface — with planning, policy, approvals, and traceable execution behind every sentence.

Developer Tools / DevEx

Workspace-centric workflows, codebase understanding, diagnostics, Git and VS Code integration, and operator shell interfaces.

Agent Orchestration

Workflows, agent delegation, approvals, event-driven execution, and runtime governance for AI infrastructure teams.

Internal Technical Automation

AI workspace operations, repeatable routines, and governed execution for internal engineering teams.

Security and Compliance

Automated vulnerability scanning, credential scrubbing, append-only hash-chained audit logs, and encrypted secrets vault for security-conscious teams.

Platform Engineering

CI/CD pipeline integration, Docker and Kubernetes inspection, cross-platform release builds, and infrastructure scanning with agent blueprints.

AI Research and Prototyping

Multi-provider LLM switching, MCP protocol support for external tool servers, and visual workflow studio for iterating on agent architectures rapidly.