mokh — AI-Powered Development Workflow Engine

mokh is an autonomous development engine designed to handle the entire software development lifecycle (SDLC). From the moment a task is assigned, mokh orchestrates specialized AI agents to scope, implement, review, audit, and deliver high-quality code.

🚀 Key Features

• End-to-End Orchestration: Automatically moves a task through Scoping, Development, Review, Security Audit, Testing, and Delivery.
• Provider Agnostic: Seamlessly use Claude, Gemini, OpenAI/Codex, or GitHub Copilot.
• Agent CLI Integration: A unique "CLI Mode" that uses your locally installed and authenticated AI CLIs (like claude or gemini), eliminating the need for API keys and reducing costs.
• Interactive Intent Clarification: mokh "grills" you with clarifying questions during the scoping phase to ensure requirements are 100% clear before a single line of code is written.
• Security-First: Integrated security auditing agent that scans every change for vulnerabilities before it ever reaches a PR.
• Full Traceability: Persistent SQLite database tracks every task, agent decision, code change, and PR.

📦 Installation

Prerequisites

• Node.js: v18.0.0 or higher.
• Git: Required for repository management and PR delivery.

Global Install

npm install -g mokh

(Optional) Install Agent CLIs

To use mokh without API keys, install your preferred agent CLIs:

• Claude: npm install -g @anthropic-ai/claude-code
• Gemini: npm install -g @google/generative-ai (or use the gcloud component)

🚦 Quick Start

1. Initialize Your Project

Run init in the root of your repository to configure mokh. It will automatically detect any installed agent CLIs.

mokh init

2. Start a Development Task

Provide a ticket ID and description. mokh will enter "Intent Clarification" mode to refine the scope.

mokh task start -t TASK-123 -d "Implement user authentication using JWT"

3. Monitor Progress

Open the interactive dashboard to see the status of your active tasks, epics, and agent usage.

mokh dashboard

🛠 Command Reference

Task Management

| Command | Description | | :--- | :--- | | mokh task start | Begin a new orchestrated development workflow. | | mokh task list | List all tasks for the current project. | | mokh history epics | View the history of completed and active epics. |

Configuration & Agents

| Command | Description | | :--- | :--- | | mokh agents detect | Show which AI CLIs are installed and ready for use. | | mokh config show | View current configuration settings. | | mokh config wizard | Interactively update your global and project settings. | | mokh config set <key> <value> | Manually update a specific configuration value. |

Insights & Reporting

| Command | Description | | :--- | :--- | | mokh report standup | Generate a summary of work done today for your standup meeting. | | mokh audit run | Run an ad-hoc security audit on the current repository. | | mokh dashboard | The "Mission Control" view for all your automated workflows. |

⚙️ Configuration

mokh uses a tiered configuration system stored in your home directory (~/.config/mokh-nodejs/).

Agent Execution Modes

Each agent (Scoping, Dev, Review, etc.) can be configured with a specific mode:

• cli (Recommended): Uses the locally installed CLI tool (e.g., claude). No API keys required.
• api: Uses the provider's web API (requires apiKey in config).
• auto: Uses the CLI if detected, otherwise falls back to API.

Example: Force Development agent to use API

mokh config set agents.development.mode api

JIRA Integration

Configure your JIRA details to allow mokh to pull task context and link PRs back to tickets.

mokh config set jira.baseUrl https://your-org.atlassian.net
mokh config set jira.projectKey PROJ

🏗 Architecture

mokh orchestrates the SDLC through a series of specialized workflow stages:

1. Scoping Agent: Analyzes the repository and task description. Asks clarifying questions.
2. Development Agent: Implements the technical plan. Refactors existing code or creates new modules.
3. Review Agent: Conducts a peer-level code review, checking for style, logic, and patterns.
4. Security Agent: Scans for vulnerabilities, hardcoded secrets, and unsafe patterns.
5. Testing Agent: Generates and executes test suites to verify the implementation.
6. Delivery Agent: Manages git branches, pushes changes, and creates Pull Requests.

🤝 Contributing

We welcome contributions! Please see our Development Guide for details on the tech stack and architecture.

1. Clone the repo: git clone https://github.com/your-repo/mokh.git
2. Install dependencies: pnpm install
3. Run in dev mode: npm run dev
4. Run tests: npm test