Show HN: Tinycoder is a tiny provider-agnostic alt. to Codex/Code/Gemini CLI

Your command-line AI coding assistant 🤖 integrated with Git! Pure Python, zero dependencies.

TinyCoder is a Python-based tool designed to help you interact with Large Language Models (LLMs) for coding tasks directly within your terminal. It analyzes your codebase, builds context for the LLM, applies suggested code changes safely, and integrates seamlessly with your Git workflow. Minimal dependencies, maximum productivity!

• 💻 Command-Line Interface: Smooth terminal interaction with multiline input and potential path autocompletion.
• 📓 Jupyter Notebook Support: Read, edit, and write .ipynb files. Notebooks are automatically converted to a plain Python representation for the LLM and converted back to .ipynb format upon saving.
• 🧠 Intelligent Context Building:
  • File Management: Easily add/remove files (/add, /drop, /files).
  • Automatic File Identification: Suggests relevant files to add to the context based on your request (/ask for files feature).
  • Repo Map: Generates a high-level codebase map (RepoMap) for broader LLM understanding. Controlled via /repomap [on|off|show].
  • Customizable Repo Map Exclusions: Fine-tune the RepoMap by adding or removing exclusion patterns for files/directories via /repomap exclude add|remove|list.
  • Code Snippet Context: Quickly add specific functions or classes to the context using @path/to/file.py::EntityName syntax in your prompts (e.g., @app.py::MyClass).
  • Smart Prompts: Constructs detailed prompts using file content and repo structure (PromptBuilder).
• 🤖 Multiple LLM Support: Works with Google Gemini, DeepSeek, Anthropic, Together AI, Groq, and Ollama. Configure via --provider and --model flags, or environment variables (GEMINI_API_KEY, DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, TOGETHER_API_KEY, GROQ_API_KEY).
• ✏️ Safe Code Editing:
  • Parses LLM responses using a structured XML format (EditParser).
  • Applies changes with user confirmation and diff previews (CodeApplier).
  • Handles file creation and modification reliably.
  • Linting & Reflection: Automatically lints applied code and prompts user to let the LLM fix errors.
• 🔄 Modes of Operation: Switch between code mode (for edits) and ask mode (for questions) using /code and /ask.
• 🌿 Git Integration:
  • Initializes Git repo if needed (GitManager).
  • Commits changes applied by the last successful LLM edit (/commit).
  • Rolls back the last TinyCoder commit (/undo).
• ✅ Linters & Validation: Includes built-in linters for Python, HTML, and CSS to catch issues after applying edits, with an option to auto-fix.
• 📜 Rules Engine:
  • Define project-specific coding standards (e.g., style_guide.md) in .tinycoder/rules/ (custom) or use built-in rules.
  • Manage active rules per-project using /rules list|enable|disable.
  • Configuration stored in the user's standard application config directory.
• 🧪 Test Runner: Execute project unit tests (using Python's unittest framework) using the /tests command (test_runner.py).
• 💾 Chat History: Persists conversations to tinycoder_chat_history.md in a tinycoder subdirectory within your user's standard application data directory (location varies by OS, e.g., ~/.local/share/tinycoder/ on Linux) (ChatHistoryManager) and allows resuming with --continue-chat.
• 🐳 Docker Integration (Experimental):
  • Helps manage Docker workflows alongside coding changes.
  • Can identify affected Docker services based on modified files if a docker-compose.yml is present.
  • Prompts to rebuild or restart services if live-reload isn't detected (requires Docker and docker-compose).
  • Provides commands like /docker ps, /docker logs <service>, /docker restart <service>, /docker build <service>, and /docker exec <service> <command>.
  • Warns about files in context that might not be covered by Docker volume mounts.
• ⚙️ Command Handling: Rich set of commands for session control (CommandHandler).
• 🐚 Shell Execution: Run shell commands directly using !<command>. Output can optionally be added to the chat context.
• 📝 Built-in Text Editor: A simple, integrated text editor (/edit <filename>) for quick modifications with features like:
  • Syntax highlighting (Python).
  • Line numbers and status bar.
  • Basic editing: insert, delete, tab, enter with auto-indent.
  • Navigation: arrows, Home/End, PageUp/PageDown.
  • Find functionality (Ctrl+F, F3 for next).
  • File saving (Ctrl+S) and quitting (Ctrl+Q) with unsaved changes confirmation.
  • Mouse support for cursor placement.

Requirements: Python 3.8+

Option 1: Install directly from GitHub

Option 2: Clone and install locally

🔑 API Keys:

• Set the required environment variables for your chosen cloud LLM provider:
  • Gemini: GEMINI_API_KEY
  • DeepSeek: DEEPSEEK_API_KEY
  • Anthropic: ANTHROPIC_API_KEY
  • Together AI: TOGETHER_API_KEY
  • Groq: GROQ_API_KEY
• Ollama runs locally and does not require an API key.
• You can also set OLLAMA_HOST if your Ollama instance is not at the default http://localhost:11434.

Start TinyCoder in your project's root directory:

You can specify the LLM provider and model:

Quick Command Reference:

• /add <file1> ["file 2"]...: Add file(s) to the chat context.
• /drop <file1> ["file 2"]...: Remove file(s) from the chat context.
• /files: List files currently in the chat.
• /suggest_files [instruction]: Ask the LLM to suggest relevant files. Uses last user message if no instruction.
• Pro Tip for Context: Use @path/to/file.py::EntityName (e.g., @src/utils.py::helper_function) in your messages to include specific code snippets directly.
• /edit <filename>: Open the specified file in a built-in text editor.
• /ask: Switch to ASK mode (answer questions, no edits).
• /code: Switch to CODE mode (make edits).
• /commit: Commit the changes applied by the last successful LLM edit.
• /undo: Revert the last TinyCoder commit.
• /tests: Run project unit tests (using Python's unittest framework in ./tests).
• /rules list: List available rules and their status for the project.
• /rules enable <rule_name>: Enable a specific rule.
• /rules disable <rule_name>: Disable a specific rule.
• /repomap [on|off|show]: Enable, disable, or show the inclusion of the repository map in prompts.
• /repomap exclude add <pattern>: Add a file/directory pattern to exclude from RepoMap.
• /repomap exclude remove <pattern>: Remove an exclusion pattern.
• /repomap exclude list: List current exclusion patterns.
• /docker ps: Show status of docker-compose services.
• /docker logs <service_name>: Stream logs for a service.
• /docker restart <service_name>: Restart a service.
• /docker build <service_name>: Build a service.
• /docker exec <service_name> <command...>: Execute a command in a service container.
• /clear: Clear the chat history.
• /reset: Clear history and remove all files from context.
• /help: Show help message.
• /quit or /exit or Ctrl+C/Ctrl+D: Exit.
• !<command>: Execute a shell command. You'll be prompted to add the output to the chat.

Contributions are welcome! Please read the CONTRIBUTING.md file (if it exists) for guidelines. (Placeholder - create this file if needed)

This project is licensed under the AGPLv3+ License. If you need a different license, please contact me at [email protected].

TinyCoder draws inspiration and ideas from the excellent Aider.Chat project.