G-Coder 🚀

AI-powered CLI coding assistant with multi-provider support and intelligent automation

Why G-Coder?

✅ Universal Provider Support - Use ANY OpenAI-compatible API (Ollama, DeepSeek, OpenAI, Groq, Together AI, etc.) ✅ 100% Free Option - Run locally with Ollama (no API costs) ✅ Smart Project Memory - Persistent conversation history per project ✅ Auto Token Management - Seamless continuation when limits hit ✅ Advanced Security - OS-aware risk detection and approval system ✅ Highly Customizable - Custom commands, hooks, and configurations

📦 Installation

npm install -g @prdpspkt/g-coder

🚀 Quick Start

1. Run G-Coder (Auto Setup)

g-coder

First run creates default config with Ollama (local, free). If you need API providers, interactive setup will guide you.

2. Manual Setup (Optional)

For Ollama (Free, Local):

# Install Ollama
brew install ollama  # macOS
# or: https://ollama.ai/download

# Start and pull model
ollama serve
ollama pull codellama

# G-Coder default config already set for Ollama!

For API Providers (DeepSeek, OpenAI, etc.):

Edit ~/.g-coder/config.json:

{
  "provider": "deepseek",
  "model": "deepseek-chat",
  "baseUrl": "https://api.deepseek.com/v1",
  "apiKeyName": "DEEPSEEK_API_KEY"
}

Add API key to ~/.g-coder/.env:

echo "DEEPSEEK_API_KEY=sk-your-key" >> ~/.g-coder/.env

⚙️ Configuration

Supported Providers

G-Coder works with ANY OpenAI-compatible API:

| Provider | baseUrl | Model Example | |----------|---------|---------------| | Ollama | http://localhost:11434/v1 | codellama, deepseek-coder | | DeepSeek | https://api.deepseek.com/v1 | deepseek-chat, deepseek-reasoner | | OpenAI | https://api.openai.com/v1 | gpt-4, gpt-3.5-turbo | | Groq | https://api.groq.com/openai/v1 | llama-3.1-70b-versatile | | Together AI | https://api.together.xyz/v1 | meta-llama/Llama-3-70b | | Custom | https://your-api.com/v1 | Any model name |

Note: Anthropic Claude uses its own API format: https://api.anthropic.com/v1

Configuration Structure

~/.g-coder/config.json:

{
  "provider": "your-provider-name",
  "model": "model-name",
  "baseUrl": "https://api.example.com/v1",
  "apiKeyName": "YOUR_API_KEY_ENV_VAR",
  "temperature": 0.7,
  "maxTokens": 8192,
  "approval": {
    "enabled": true,
    "toolsRequiringApproval": {
      "Bash": true,
      "Write": true,
      "Edit": true
    }
  }
}

~/.g-coder/.env:

YOUR_API_KEY_ENV_VAR=your-actual-api-key

📘 See CONFIGURATION.md for detailed examples

📚 Usage

Start Interactive Session

g-coder              # Start with default config
g-coder start        # Explicit start
g-coder start -v     # Verbose logging
g-coder setup        # Run setup wizard

In-Session Commands

Basic:

• /help - Show help
• /clear - Clear conversation
• /tools - List available tools
• /exit - Exit application

Configuration:

• /config - Show configuration
• /model - Change model
• /approval - Manage approval settings

History & Sessions:

• /history - View conversation history
• /save <name> - Save current session
• /load <name> - Load saved session
• /sessions - List all sessions

🛠️ Available Tools

G-Coder provides intelligent tools for coding tasks:

File Operations

• Read - Read file contents
• Write - Create/overwrite files (approval required)
• Edit - Smart file editing with fuzzy matching (approval required)
• NotebookEdit - Edit Jupyter notebooks (approval required)

Search

• Glob - Find files by pattern (**/*.ts)
• Grep - Search code with regex

Execution

• Bash - Run shell commands (approval required)
• BashOutput - Read background process output
• KillShell - Stop background processes

Git

• GitStatus, GitDiff - View changes
• GitCommit, GitPush - Create commits and push (approval required)

Web

• WebFetch - Fetch web content (approval required)

🔒 Security & Approval

Risk-Based Approval System

Operations are categorized by risk:

• 🟢 Safe (no approval): Read, Glob, Grep, GitStatus, GitDiff
• 🟡 Medium (approval): Write, Edit, WebFetch
• 🟠 High (approval): Bash, GitCommit
• 🔴 Critical (approval): GitPush, destructive operations

OS-Aware Security

Automatically detects dangerous patterns:

Windows: del /s, format, registry modifications Linux/Mac: rm -rf /, sudo rm, root operations

Auto-Approve

When approving, choose "auto-approve similar" to skip future prompts for the same operation.

🧠 Project Intelligence

Automatic Features

• Project Detection - Recognizes Node.js, Python, Go, Rust, etc.
• Persistent History - Last 50 interactions saved per project
• Context Restoration - Previous conversations loaded on startup
• Smart Scanning - Understands project structure automatically

Startup Context Example

📚 Previous Conversation Context:
   Previous session: 2025-01-15 10:30
   Total interactions: 42 messages
   Recent topics: Implemented auth; Fixed DB connection
   Loaded 5 interactions for context

♾️ Token Management

G-Coder handles token limits automatically:

90% Warning:

⚠️  Approaching limit: 7200/8000 tokens (90%)

100% Auto-Save:

⚠️  Token Limit Exceeded
    Auto-saving and continuing...

✓ Saved: auto-save-2025-01-15T10-30-45
  Session ID: abc123
  Load with: /load abc123

✓ Ready to continue!

No manual intervention needed!

🎨 Customization

Custom Slash Commands

Create ~/.g-coder/commands/review.md:

---
description: Review code for best practices
---

Review this project for:
1. Code quality
2. Potential bugs
3. Security issues

Usage: /review

Event Hooks

Create ~/.g-coder/hooks.json:

{
  "enabled": true,
  "hooks": {
    "session_start": ["git fetch"],
    "session_end": ["git status"]
  }
}

🆚 G-Coder vs Claude Code

| Feature | G-Coder | Claude Code | |---------|---------|-------------| | Multi-Provider | ✅ Ollama, DeepSeek, OpenAI, Groq, etc. | ❌ Claude only | | Free Option | ✅ Ollama (local, free) | ❌ Requires API | | Project History | ✅ Persistent per-project | ❌ Session only | | Auto Token Mgmt | ✅ Auto-save & continue | ❌ Manual | | OS-Aware Security | ✅ Risk detection | ⚠️ Basic | | Customization | ✅ Commands, hooks, configs | ❌ Limited |

Choose G-Coder if you want:

• 🆓 Free local models
• 🔄 Provider flexibility
• 📚 Project memory
• ♾️ Automatic continuation
• 🔒 Advanced security
• 🎨 Full customization

📖 Documentation

• CONFIGURATION.md - Detailed provider setup (7+ examples)
• config.examples.json - Ready-to-use configs
• MINIMAL_SYSTEM_PROMPT.md - System prompt guide
• TOOLS_REFERENCE.md - Complete tool documentation

🐛 Troubleshooting

Ollama not connecting:

ollama serve          # Start Ollama
ollama pull codellama # Pull model
g-coder test         # Test connection

API key not found:

cat ~/.g-coder/.env  # Check API key
g-coder config --show # Verify config

Config corrupted:

• G-Coder auto-creates backup and fresh config
• Check ~/.g-coder/config.json.backup.*

🤝 Contributing

Contributions welcome! Please submit PRs.

git clone https://github.com/prdpspkt/g-coder.git
cd g-coder
npm install
npm run build

📝 License

MIT License - see LICENSE

📬 Support

• Issues: https://github.com/prdpspkt/g-coder/issues
• NPM: https://www.npmjs.com/package/@prdpspkt/g-coder

Made with 🚀 by developers, for developers

श्री गणेशाय नम: