AI Coding Agent

A powerful conversational AI agent that interacts with your file system using DeepSeek's API. Features persistent memory, multi-turn conversations, and real-time streaming responses.

Features

Persistent Memory

• Session-based conversations - Agent remembers context across interactions
• File system memory - Tracks files it has seen, their sizes, and metadata
• User notes - Agent can store and recall important information
• Disk persistence - Conversations survive browser refreshes and server restarts
• Tool history - Tracks all actions taken during a session

Multi-Turn Conversations

• Maintains conversation context across multiple exchanges
• References previous interactions naturally
• Understands follow-up questions and clarifications
• Example: "Remember my config file path" → "What was that config path again?"

File System Operations

• Read - View contents of any text file
• Write - Create or overwrite files with content
• Create directories - Build folder structures
• Delete - Remove files or empty directories
• Move/Rename - Organize files and folders
• List directory - Explore folder contents
• File info - View size, creation/modification dates
• Search - Find files by pattern or content

Web Fetching Capabilities

• fetch_url - Fetch any URL (web pages, APIs, text files)
• fetch_and_parse_json - Fetch and parse JSON APIs automatically
• download_file - Download and save files from the web

PostgreSQL Database Integration

• pg_query - Execute any SQL query with parameterization
• pg_list_tables - List all tables with metadata
• pg_describe_table - Get detailed table schema
• pg_get_schema - Export full database schema
• pg_generate_data - Generate random test data
• pg_table_stats - Get table statistics and metrics
• pg_create_table - Create new tables
• pg_alter_table - Modify existing tables
• pg_drop_table - Delete tables (with caution)
• pg_list_indexes - Show indexes on tables
• pg_list_foreign_keys - Show relationships
• pg_list_sequences - List sequences
• pg_transaction - Atomic multi-query transactions

Git Version Control

• git_init - Initialize new repository
• git_status - Show current state
• git_add - Stage files
• git_commit - Commit with message
• git_branches - List branches
• git_create_branch - Create new branch
• git_checkout - Switch branches
• git_delete_branch - Delete branches
• git_log - View history
• git_diff - See changes
• git_reset_hard - Discard changes
• git_reset_soft - Unstage changes
• git_revert - Undo commit safely
• git_stash - Save changes temporarily
• git_stash_pop - Restore stashed changes
• git_merge - Merge branches
• git_file_history - File history
• git_uncommitted_files - List changed files
• git_create_tag - Create tags
• git_tags - List tags

Smart Features

• Real-time streaming - Watch the agent think and act step-by-step
• Natural language - Describe what you want in plain English
• Path safety - Prevents directory traversal attacks
• Error handling - Clear feedback when something goes wrong
• Progress tracking - See step counts, tool usage, and elapsed time

Memory Tools

• remember_note - Store important information
• recall_notes - Retrieve previously stored notes
• search_files - Find files by name pattern
• File tracking - Automatically remembers files it encounters

User Interface

• Clean, modern chat interface
• Real-time streaming output
• Session management (new chat, clear history)
• Example prompts for quick testing
• Memory statistics (files seen, notes, actions)
• Keyboard shortcuts (Enter to send)

Quick Start

Prerequisites

• Node.js (v16 or higher)
• DeepSeek API key (Get one here)

Installation

# Clone or create the project
mkdir mecha-ui
cd mecha-ui

# Install dependencies
npm install

# Create .env file with your API key
echo "DEEPSEEK_API_KEY=your-deepseek-key-here" > .env
echo "DEEPSEEK_MODEL=deepseek-chat" >> .env
echo "WORKSPACE_DIR=./workspace" >> .env

# Create workspace folder
mkdir -p apps

# Start the server
npm start

Usage

1. Open localhost:3000 in your browser
2. Type a command in the chat input
3. Watch the agent process your request in real-time
4. Continue the conversation - the agent remembers context!

📝 Example Conversations

File Management

User: "Create a folder called 'project' and add a README.md"
Agent: ✅ Created directory: project
       ✅ Wrote project/README.md (48 characters)

Memory & Recall

User: "Remember that my config is in ./config/settings.json"
Agent: 💭 Remembered: "config is in ./config/settings.json"

User: "Where is my config file?"
Agent: You asked me to remember that your config is at ./config/settings.json. 
       Would you like me to read it?

Example Web Operations

User: "Get weather data from the OpenWeatherMap API"
Agent: 🌐 Fetching API data...
       📊 Weather: Sunny, 22°C
       💾 Saved to: weather.json

Example Database Tasks

Explore Database:

User: "What tables are in the database?"
Agent: 📋 Tables in public (12):
       📊 users (8 columns)
       📊 products (6 columns)
       📊 orders (7 columns)

Custom Queries:

User: "Find all orders over $1000 from the last month"
Agent: 🐘 Executing SQL query...
       ✅ Found 43 orders

Complex Operations

User: "Find all JavaScript files, check if they have tests"
Agent: 🔍 Searching for *.js files...
       Found 3 JS files
       📖 Reading app.js...
       📖 Reading utils.js...
       📖 Reading test.js...

Example Git Workflows

Initialize and commit:

User: "Initialize git and commit all files"
Agent: ✅ Repo initialized
       ✅ Committed: Initial commit

Feature branch workflow:

User: "Create feature branch, add code, merge"
Agent: 🌿 Created branch: feature/new
       ✅ Committed changes
       🔀 Merged to main

Safe undo:

User: "Revert the last commit"
Agent: ✅ Reverted commit safely
       🔄 New commit created

🛠️ Architecture

Browser (UI)
    ↓
HTTP/SSE
    ↓
Express Server
    ↓
DeepSeek Agent
    ├── Session Manager
    │   ├── Conversation History
    │   ├── File Memory
    │   └── User Notes
    ├── Tool Executor
    │   ├── File Operations
    │   └── Memory Operations
    └── File System (./workspace)

🔒 Security

• Path traversal protection - Agent cannot access files outside the workspace
• Sandboxed workspace - All operations confined to ./workspace directory
• Input validation - All user inputs are validated before processing
• Rate limiting - Prevents excessive API usage
• Session timeout - Inactive sessions expire automatically

📦 Dependencies

• express - Web server
• ejs - Template rendering
• openai - DeepSeek API client (OpenAI-compatible)

🗂️ Project Structure

mecha-ui/
├── server.js              # Express server with endpoints
├── agent-memory.js        # DeepSeek agent with memory
├── session-manager.js     # Session and memory management
├── index.html             # Frontend UI
├── package.json           # Dependencies and scripts
├── .env                   # Configuration
├── workspace/             # Agent's sandboxed file system
│   └── .memory/           # Persistent session storage
└── README.md              # This file

🔧 API Endpoints

Endpoint	Method	Description
/api/execute-stream	POST	Execute a command with streaming response
/api/session/:sessionId	GET	Get session information
/api/sessions	GET	List all active sessions
/api/session/:sessionId	DELETE	Delete a specific session
/api/sessions	DELETE	Clear all sessions

🎨 Customization

Change Model

Edit .env:

DEEPSEEK_MODEL=deepseek-reasoner  # For complex reasoning tasks

Increase Context Window

Edit session-manager.js:

const MAX_HISTORY_TURNS = 100;  // Keep more conversation history

Change Workspace

Edit .env:

WORKSPACE_DIR=/path/to/your/folder

🚦 Status Indicators

• 🟡 Running - Agent is processing your request
• 🟢 Done - Task completed successfully
• ⚪ Idle - Waiting for input

💰 Cost Efficiency

Using DeepSeek makes this agent extremely cost-effective:

• DeepSeek-Chat: ~$0.14 per 1M input tokens
• DeepSeek-Reasoner: ~$0.55 per 1M input tokens
• Typical request cost: < $0.001 per interaction

🐛 Troubleshooting

"Invalid API Key"

• Check your .env file
• Ensure DEEPSEEK_API_KEY starts with sk-
• Visit DeepSeek Platform to verify your key

"Connection refused"

• Ensure server is running (npm start)
• Check port 3000 is not in use
• Verify browser can access http://localhost:3000

"Rate limit exceeded"

• Wait a few seconds and try again
• Consider upgrading your DeepSeek plan

"Access denied" errors

• Ensure operations are within ./apps
• Check file/folder permissions
• Verify paths are relative to workspace

🔮 Future Enhancements

• Semantic search with embeddings
• Multi-file operations with pattern matching
• File watching and auto-reactions
• Visual file explorer
• Batch operation scheduling
• Export/Import conversation history
• Voice input support
• Integration with version control (Git)

📄 License

GPL

⚠️ Disclaimer

This agent has file system access. Always:

• Use a dedicated workspace folder
• Never point it to system-critical directories
• Review all operations before executing
• Keep backups of important data

---

Built with ❤️ using DeepSeek API