DevFlow - AI-Powered DevOps Platform

Status: ✅ Production Ready | Version: 0.2.0 | Challenge: GitHub Copilot CLI Challenge

DevFlow is a complete SaaS platform + self-hosted CLI agent that orchestrates AI-powered development workflows using the GitHub Copilot SDK.

🎯 What is DevFlow?

Unlike traditional CLI tools, DevFlow enables teams to:

🌐 Use a cloud-based SaaS dashboard for task management
🔒 Run a self-hosted agent locally for code privacy
🤖 Execute complex workflows powered by GitHub Copilot (fix bugs, implement features, explain code, review PRs)
📱 Receive real-time notifications via Slack/Telegram
🔗 Integrate seamlessly with GitHub repositories

🚀 Quick Start

Install the CLI

npm install -g @untools/devflow

Initialize

devflow init
# Authenticate with GitHub

Start the Agent

devflow start
# Agent polls for tasks every 5 seconds

Create a Task

Visit the web dashboard and create a task. Watch your agent execute AI workflows!

📦 What's Included

1. Pinga Web Platform (SaaS Dashboard)

Next.js 14 + MongoDB
OAuth authentication
Task creation & monitoring
Real-time notifications
11 REST API endpoints

2. DevFlow CLI Agent (`@untools/devflow`)

3 simple commands: init, start, status
Task polling every 5 seconds
Secure JWT token management
Runs locally on your machine

3. Agent-Host (Copilot SDK Engine)

Real integration with @github/copilot-sdk
4 AI-powered workflows
7 integrated tools (git, files, tests, GitHub API, etc.)
Executes on your machine—code never leaves

💡 Workflows

Workflow	What It Does
fix-bug	Analyzes issue → implements fix → runs tests → creates PR
feature	Implements new feature with tests and documentation
explain	Generates documentation for code
review-pr	Reviews pull requests for best practices

🏗 Architecture

┌─────────────────────────────────┐
│  Web Platform (SaaS Dashboard)  │
│  - Task management              │
│  - Notifications                │
│  - User management              │
└─────────────────────────────────┘
              ↑ (HTTP/REST)
              │
┌─────────────────────────────────┐
│  CLI Agent (Self-Hosted)        │
│  - Polls for tasks              │
│  - Secure authentication        │
│  - Task execution coordination  │
└─────────────────────────────────┘
              ↓ (Local HTTP)
┌─────────────────────────────────┐
│  Agent-Host (Local)             │
│  - Copilot SDK integration      │
│  - Workflow execution           │
│  - Tool management              │
└─────────────────────────────────┘

📊 Project Statistics

40,000+ lines of TypeScript
3 independent applications
11 REST API endpoints
4 AI-powered workflows
7 integrated tools
60,000+ words of documentation
0 TypeScript errors (all 3 apps compile)

📚 Documentation

Comprehensive guides available:

GETTING_STARTED.md - 5-minute quick start
API_REFERENCE.md - Complete API specification
CHALLENGE_SUBMISSION.md - Challenge details
PROJECT_SUMMARY.md - Full project overview
E2E_TESTING.md - Testing guide
TROUBLESHOOTING.md - Solutions
PRODUCTION_DEPLOYMENT.md - Deployment guide

📖 Comprehensive Getting Started Guide

1. System Requirements

Before you begin, ensure you have the following installed:

Node.js: 18.0.0 or later
npm: 9.0.0 or later
MongoDB: Local instance or MongoDB Atlas connection
Git: For repository cloning
Operating System: macOS, Linux, or Windows (WSL2 recommended for Windows)

Check your versions:

node --version    # Should output v18.0.0 or higher
npm --version     # Should output 9.0.0 or higher

2. Initial Setup

Step 1: Clone and Install

# Clone the repository
git clone https://github.com/untools/devflow.git
cd devflow

# Install dependencies for all workspaces
npm install

This installs dependencies for three applications:

apps/web - Next.js SaaS dashboard
apps/agent-host - Copilot SDK engine
apps/agent - CLI agent

Step 2: Environment Configuration

Create .env.local files for each application:

apps/web/.env.local

# Database
MONGODB_URI=mongodb://localhost:27017/devflow

# Authentication
JWT_SECRET=your-super-secret-key-change-this
JWT_EXPIRY=2592000  # 30 days in seconds

# GitHub OAuth (create app at https://github.com/settings/developers)
GITHUB_OAUTH_CLIENT_ID=your-github-app-id
GITHUB_OAUTH_CLIENT_SECRET=your-github-app-secret

# Telegram Integration (optional)
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id

# Slack Integration (optional)
SLACK_WEBHOOK_URL=your-webhook-url

# Agent-Host
AGENT_HOST_URL=http://localhost:3001
DEVFLOW_API_SECRET=test-secret-123

apps/agent-host/.env.local

# GitHub
GITHUB_TOKEN=ghp_your-personal-access-token

# Copilot
COPILOT_API_KEY=your-copilot-key

# Platform Communication
DEVFLOW_API_SECRET=test-secret-123
DEVFLOW_API_URL=http://localhost:3000

# Server
PORT=3001
NODE_ENV=development

apps/agent/.env.local

# Platform
DEVFLOW_PLATFORM_URL=http://localhost:3000

# Agent
AGENT_ID=local-agent-dev
AGENT_NAME=My DevFlow Agent

# Authentication
DEVFLOW_AGENT_TOKEN=your-jwt-token
DEVFLOW_API_SECRET=test-secret-123

Step 3: Database Setup

Option A: Local MongoDB

# Install MongoDB via Homebrew (macOS)
brew tap mongodb/brew
brew install mongodb-community

# Start MongoDB
brew services start mongodb-community

# Verify it's running
mongo --eval "db.version()"

Option B: MongoDB Atlas (Cloud)

Create account at https://www.mongodb.com/cloud/atlas
Create a cluster and get connection string
Update MONGODB_URI in apps/web/.env.local

3. Running Services Locally

DevFlow consists of 3 independent services. Run each in a separate terminal:

Terminal 1: Web Platform (Next.js)

npm run dev --workspace=apps/web
# Runs on http://localhost:3000
# Dashboard for task management and monitoring

Terminal 2: Agent-Host (Copilot Engine)

npm run dev --workspace=apps/agent-host
# Runs on http://localhost:3001
# Real-time workflow execution engine

Terminal 3: CLI Agent

npm run dev --workspace=apps/agent -- cli start
# Polls platform every 5 seconds for tasks
# Executes tasks via Agent-Host

Once all three are running, you should see:

Web Platform: "✓ Next.js ready in Xms"
Agent-Host: "Server running on port 3001"
CLI Agent: "✓ Connected successfully" and "Waiting for tasks..."

4. Your First Workflow

Option A: Web Dashboard (Easiest)

Open the dashboard
```
http://localhost:3000
```
Authenticate
- Click "Sign In"
- GitHub OAuth flow
- Complete authentication
Create an Agent
- Dashboard → Agents → Register
- Name: "local-dev"
- Save the Agent ID

Create Your First Task

Click "Create Task"
Select Intent: explain
Paste this code:

function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

Click "Execute"

Watch the Agent Work
- Monitor in CLI agent terminal
- See progress updates in real-time
- View generated documentation

Option B: Direct CLI Usage

# 1. Initialize the agent
devflow init
# Follow prompts for platform URL and authentication

# 2. Start polling for tasks
devflow start

# 3. In another terminal, create a task via API
curl -X POST http://localhost:3000/api/tasks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "local-agent-dev",
    "intent": "explain",
    "description": "Explain the fibonacci function",
    "payload": {
      "code": "function fib(n) { if (n <= 1) return n; return fib(n-1) + fib(n-2); }"
    }
  }'

5. Common Workflows

Fix a Bug

Identify the issue:
- Repository: owner/repo
- Issue description: "Fix authentication error on login"

Create task:

devflow task create \
  --intent fix-bug \
  --repo owner/repo \
  --description "Fix authentication error on login"

Agent executes:
- Clones repository
- Analyzes issue
- Implements fix
- Runs tests
- Creates pull request

Implement a Feature

Plan the feature:
- Specification: "Add dark mode toggle"

Create task:

devflow task create \
  --intent feature \
  --repo owner/repo \
  --description "Implement dark mode with persistent storage"

Agent builds:
- Analyzes codebase
- Plans architecture
- Writes implementation
- Adds tests
- Creates documentation
- Opens PR

Explain Code

devflow task create \
  --intent explain \
  --description "Explain how the auth middleware works" \
  --code-path src/middleware/auth.ts

Review Pull Request

devflow task create \
  --intent review-pr \
  --repo owner/repo \
  --pr-number 42 \
  --description "Review for security and performance"

6. Troubleshooting Common Issues

Issue: "Cannot connect to MongoDB"

# Verify MongoDB is running
ps aux | grep mongod

# Start MongoDB if not running
brew services start mongodb-community

Issue: "Agent won't start - ECONNREFUSED"

# Ensure all 3 services are running
curl http://localhost:3000/health  # Web platform
curl http://localhost:3001/health  # Agent-Host

# If not responding, restart the service

Issue: "Authentication failed - Invalid token"

# Re-initialize with fresh credentials
devflow init

# Or manually update token in config
cat ~/.devflow/config.json  # View config

Issue: "Tasks not completing"

# Check service logs for errors
# View CLI Agent terminal for error messages

# Verify all services have proper environment variables
env | grep DEVFLOW

# Check network connectivity
curl -I http://localhost:3000
curl -I http://localhost:3001

7. Development Tips

Live Reload: All services support hot-reload during development.

Debugging: View detailed logs:

# In CLI agent terminal
devflow start --log-level debug

# Check web platform logs
npm run dev --workspace=apps/web -- --debug

Testing Your Changes:

# Run linter across all apps
npm run lint

# Run tests if available
npm test

# Build all applications
npm run build

Database Reset:

# Connect to MongoDB and drop database
mongo
> use devflow
> db.dropDatabase()
> exit

8. Next Steps

Once you're familiar with the basics:

Connect to Real GitHub
- Register your GitHub App
- Deploy to production server
- Monitor real workflow executions
Set Up Notifications
- Configure Telegram integration
- Set up Slack webhooks
- Real-time updates to your chat
Advanced Configuration
- Custom workflows
- Extended tool integration
- Performance optimization
Production Deployment
- See PRODUCTION_DEPLOYMENT.md
- Docker containerization
- Cloud deployment (Render, Vercel, AWS)

🛠 Development Setup

Prerequisites

Node.js 18+
MongoDB (local or Atlas)
GitHub account

Installation

# Clone repository
git clone https://github.com/untools/devflow.git
cd devflow

# Install dependencies
npm install

# Start services (3 terminals)
# Terminal 1: Web Platform
npm run dev --workspace=apps/web
# http://localhost:3000

# Terminal 2: Agent-Host
npm run dev --workspace=apps/agent-host
# http://localhost:3001

# Terminal 3: CLI Agent
npm run dev --workspace=apps/agent -- cli start

Environment Variables

# apps/web/.env.local
MONGODB_URI=mongodb://localhost:27017/devflow
JWT_SECRET=<random-secret>
GITHUB_OAUTH_CLIENT_ID=<your-github-app-id>
GITHUB_OAUTH_CLIENT_SECRET=<your-github-app-secret>

🔐 Security

✅ OAuth 2.0 authentication
✅ JWT tokens (30-day expiry)
✅ Secure config storage (mode 0o600)
✅ Local code execution (code never uploaded)
✅ Bearer token authentication on all APIs

📦 Applications

apps/web

Next.js 14 SaaS platform with MongoDB

User authentication
Agent management
Task creation & monitoring
Real-time notifications

apps/agent

npm package @untools/devflow

CLI: devflow init, devflow start, devflow status
Task polling from platform
Secure configuration management

apps/agent-host

Express.js server with Copilot SDK

Real @github/copilot-sdk integration
Workflow execution engine
Tool definitions and execution

🚀 Publishing

Ready to publish to npm:

cd apps/agent
npm publish --access public

Users can then install globally:

npm install -g @untools/devflow

📋 Checklist

✅ Built with GitHub Copilot SDK
✅ Complete CLI tool
✅ Innovative two-tier architecture
✅ Production-ready code (40,000+ LOC)
✅ Comprehensive documentation (60,000+ words)
✅ All 3 apps compile (0 errors)
✅ Ready for GitHub Copilot CLI Challenge

📄 License

MIT

🔗 Links

npm: @untools/devflow
GitHub: github.com/untools/devflow
Challenge: GitHub Copilot CLI Challenge
Deadline: February 15, 2025 (Submitted January 24 - 22 days early)

Built with ❤️ for the GitHub Copilot CLI Challenge

Name		Name	Last commit message	Last commit date
Latest commit History 240 Commits
.context		.context
apps		apps
docs		docs
scripts/copilot-demo		scripts/copilot-demo
tools		tools
.gitignore		.gitignore
README.md		README.md
debug-telegram-auth.ts		debug-telegram-auth.ts
package-lock.json		package-lock.json
package.json		package.json
tree.md		tree.md

aevrHQ/devflow

Folders and files

Latest commit

History

Repository files navigation