# NC1709 - A Local-First AI Developer Assistant

<p align="center">
  <strong>Your code stays on your machine. Always.</strong>
</p>

<p align="center">
  <a href="#installation">Installation</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#features">Features</a> •
  <a href="#remote-mode">Remote Mode</a> •
  <a href="#extensions">Extensions</a>
</p>

---

NC1709 is a powerful, **100% local** AI developer assistant. Unlike cloud-based tools, your code and conversations never leave your computer unless you choose to share your server with others.

## What's New in v1.6.0

- **VS Code Extension** - Full IDE integration with inline completions
- **Desktop App** - Native Electron app for macOS, Windows, Linux
- **Smart Task Classifier** - LLM-powered intelligent task routing
- **Auto-Fix Agent** - Automatically detect and fix code errors
- **Test Generator** - Generate unit tests for your functions
- **Shell Completions** - Tab completion for bash, zsh, and fish
- **Progress Indicators** - Rich progress bars and spinners

## Installation

```bash
# Install from PyPI
pip install nc1709

# Or install with all features (web dashboard, memory, etc.)
pip install nc1709[all]

# Enable shell completions (optional)
nc1709 --completion bash >> ~/.bashrc  # or zsh/fish
```

### Prerequisites

1. **Python 3.9+**
2. **Ollama** - Local LLM server
   ```bash
   curl -fsSL https://ollama.com/install.sh | sh
   ```
3. **Download models**
   ```bash
   ollama pull qwen2.5-coder:32b
   ollama pull qwen2.5:32b
   ```

## Quick Start

```bash
# Interactive shell mode
nc1709

# Direct command
nc1709 "create a Python script to fetch JSON from an API"

# Start web dashboard
nc1709 --web

# Auto-fix errors in a file
nc1709 --fix main.py

# Generate tests for a file
nc1709 --generate-tests utils.py
```

## Features

### Core Capabilities
- **Chat Interface** - Conversational AI for coding help
- **File Operations** - Read, write, edit files safely with auto-backup
- **Command Execution** - Run shell commands in a sandboxed environment
- **Multi-Step Reasoning** - Complex tasks broken into manageable steps
- **Smart Task Classification** - Automatic model selection based on task type

### Memory & Context
- **Semantic Code Search** - Find code by meaning, not just keywords
- **Project Indexing** - Index your codebase for intelligent search
- **Session Persistence** - Save and resume conversations

```bash
# Index your project
nc1709 --index

# Semantic search
nc1709 --search "authentication logic"

# Resume a session
nc1709 --sessions
nc1709 --resume <session-id>
```

### AI Agents

**Auto-Fix Agent** - Automatically detects and fixes code errors:
```bash
nc1709 --fix src/main.py           # Analyze and suggest fixes
nc1709 --fix src/main.py --apply   # Auto-apply fixes
```

**Test Generator** - Generates unit tests for your code:
```bash
nc1709 --generate-tests utils.py   # Generate tests
nc1709 --generate-tests utils.py --output tests/test_utils.py
```

### Plugins & Agents
- **Git Agent** - Commits, branches, diffs, and more
- **Docker Agent** - Container and image management
- **Framework Agents** - FastAPI, Next.js, Django scaffolding
- **MCP Support** - Model Context Protocol integration

```bash
# In shell mode
git status
git diff
docker ps
docker compose up

# Or via CLI
nc1709 --plugin git:status
nc1709 --plugin docker:ps
```

### Web Dashboard
A full browser-based interface for NC1709:

```bash
nc1709 --web
# Open http://localhost:8709
```

Features:
- Chat with syntax highlighting
- Session management
- Semantic code search UI
- Plugin management
- MCP tools browser
- Configuration editor

## Remote Mode

Share your NC1709 instance with friends - they use your LLMs remotely!

### Server Setup
```bash
# Start server with remote access enabled
nc1709 --web --serve

# Set API key in config (~/.nc1709/config.json)
{
  "remote": {
    "api_key": "your-secret-key"
  }
}
```

### Expose to Internet
```bash
# Using Cloudflare Tunnel (recommended)
cloudflared tunnel --url http://localhost:8709

# Or ngrok
ngrok http 8709
```

### Client Setup
```bash
# Friends install nc1709
pip install nc1709

# Set environment variables
export NC1709_API_URL="https://your-tunnel-url.com"
export NC1709_API_KEY="your-secret-key"

# Use normally - your LLMs, their machine!
nc1709 "explain this code"
```

## Extensions

### VS Code Extension
Full IDE integration with:
- Chat sidebar panel
- Inline code completions (like GitHub Copilot)
- Right-click code actions (explain, refactor, test, fix)
- Keyboard shortcuts

```bash
cd vscode-extension
npm install && npm run package
# Install the .vsix file in VS Code
```

### Desktop App
Native Electron app with:
- System tray integration
- Automatic server management
- Dark/light mode support

```bash
cd desktop-app
npm install && npm start
```

## Shell Commands

In interactive mode:

```
help          Show available commands
exit          Exit the shell
clear         Clear conversation history
sessions      List saved sessions
search <q>    Semantic code search
index         Index current project
plugins       List available plugins
git <cmd>     Git operations
docker <cmd>  Docker operations
mcp           MCP status and tools
fix <file>    Auto-fix errors
test <file>   Generate tests
```

## Configuration

Config file: `~/.nc1709/config.json`

```bash
nc1709 --config  # View configuration
```

```json
{
  "models": {
    "reasoning": "deepseek-r1:latest",
    "coding": "qwen2.5-coder:32b",
    "general": "qwen2.5:32b",
    "fast": "qwen2.5-coder:7b"
  },
  "safety": {
    "confirm_writes": true,
    "auto_backup": true
  },
  "remote": {
    "api_key": "your-secret-key"
  }
}
```

## CLI Reference

```bash
nc1709 [prompt]              # Direct command or start shell
nc1709 --shell               # Interactive shell mode
nc1709 --web                 # Start web dashboard
nc1709 --web --port 9000     # Custom port
nc1709 --web --serve         # Enable remote access

# AI Agents
nc1709 --fix <file>          # Auto-fix code errors
nc1709 --generate-tests <file>  # Generate unit tests

# Memory features
nc1709 --index               # Index project
nc1709 --search "query"      # Semantic search
nc1709 --sessions            # List sessions
nc1709 --resume <id>         # Resume session

# Plugins
nc1709 --plugins             # List plugins
nc1709 --plugin git:status

# Remote mode
nc1709 --remote <url>        # Connect to remote server
nc1709 --api-key <key>       # API key for remote

# Shell completions
nc1709 --completion bash     # Generate bash completions
nc1709 --completion zsh      # Generate zsh completions
nc1709 --completion fish     # Generate fish completions

# Info
nc1709 --version             # Show version
nc1709 --config              # Show configuration
nc1709 --help                # Show help
```

## Installation Options

```bash
# Basic installation
pip install nc1709

# With memory features (ChromaDB, embeddings)
pip install nc1709[memory]

# With web dashboard
pip install nc1709[web]

# Everything
pip install nc1709[all]

# Development
pip install nc1709[dev]
```

## System Requirements

- **Python**: 3.9+
- **RAM**: 16GB minimum, 32GB recommended
- **GPU**: NVIDIA with 12GB+ VRAM (optional, CPU works but slower)
- **Storage**: ~50GB for models
- **OS**: macOS, Linux, Windows (WSL2)

## Project Structure

```
nc1709/
├── nc1709/
│   ├── cli.py              # Main CLI
│   ├── config.py           # Configuration
│   ├── llm_adapter.py      # LLM integration
│   ├── reasoning_engine.py # Multi-step reasoning
│   ├── task_classifier.py  # Smart task classification
│   ├── progress.py         # Progress indicators
│   ├── shell_completions.py # Shell completions
│   ├── file_controller.py  # File operations
│   ├── executor.py         # Command execution
│   ├── remote_client.py    # Remote mode client
│   ├── memory/             # Vector DB, sessions, indexing
│   ├── plugins/            # Plugin system & agents
│   ├── agents/             # AI agents (auto-fix, test-gen)
│   ├── mcp/                # Model Context Protocol
│   └── web/                # Web dashboard
├── vscode-extension/       # VS Code extension
├── desktop-app/            # Electron desktop app
├── docs/                   # Documentation
├── tests/                  # Test suite
├── pyproject.toml          # Package config
└── README.md
```

## Privacy & Security

- **100% Local**: All processing happens on your machine
- **No Telemetry**: Zero data collection
- **Auto-Backup**: Files backed up before modification
- **Sandboxed Execution**: Commands validated before running
- **Confirmation Prompts**: Ask before destructive operations
- **API Key Auth**: Secure remote access with authentication

## Troubleshooting

### "Cannot connect to Ollama"
```bash
ollama serve  # Start Ollama
```

### "Model not found"
```bash
ollama pull qwen2.5-coder:32b
```

### Slow performance
- Use GPU: `nvidia-smi` to verify
- Use smaller models: `qwen2.5-coder:7b`
- Clear history: `clear` in shell

### Shell completions not working
```bash
# Bash
echo 'eval "$(nc1709 --completion bash)"' >> ~/.bashrc
source ~/.bashrc

# Zsh
echo 'eval "$(nc1709 --completion zsh)"' >> ~/.zshrc
source ~/.zshrc

# Fish
nc1709 --completion fish > ~/.config/fish/completions/nc1709.fish
```

## Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT License - See [LICENSE](LICENSE) file.

## Acknowledgments

Built with [Ollama](https://ollama.com/), [LiteLLM](https://github.com/BerriAI/litellm), and open-source models from DeepSeek and Qwen.

---

**Built for developers who value privacy and control.**
