jps-forge

A 100% local, Ollama-powered coding agent that indexes your projects, answers questions about your codebase with RAG, and can autonomously run Git commands and other tools — no cloud, no API keys, no data ever leaves your machine.

🚀 Overview

jps-forge is a privacy-focused AI coding assistant that runs entirely on your local machine using Ollama. It combines retrieval-augmented generation (RAG) with autonomous tool execution to help you understand and work with your codebase without sending any data to external services.

Key Features

• 🔒 100% Local & Private: All processing happens on your machine using Ollama - no cloud APIs, no data leakage
• 📚 Intelligent Code Search: Uses FAISS vector store with sentence transformers for semantic code search
• 🤖 Autonomous Agent: Powered by LangGraph's ReAct agent that can use tools to answer questions
• 🔧 Git Integration: Built-in tools to check repository status and find uncommitted changes
• 💬 Interactive Chat: Rich terminal interface for conversational code exploration
• 🎯 Context-Aware: Retrieves relevant code snippets to provide accurate, contextual answers
• 🐳 Docker Support: Includes Dockerfile and docker-compose.yml for containerized deployment

How It Works

1. Index: Scan your codebase and create vector embeddings of your code
2. Query: Ask questions in natural language about your code
3. Retrieve: Automatically fetch relevant code context using semantic search
4. Act: Agent uses tools (git status, etc.) when needed to gather information
5. Answer: Get AI-powered responses grounded in your actual codebase

📦 Installation

Prerequisites

• Python 3.10 or higher
• Ollama installed and running
• An Ollama model pulled (e.g., ollama pull llama3.1:8b)

Install from PyPI

pip install jps-forge

Install from Source

git clone https://github.com/jai-python3/jps-forge.git
cd jps-forge
pip install -e .

Docker

See the Usage Guide for detailed Docker deployment instructions.

Quick start with docker-compose:

docker-compose up -d
docker-compose exec jps-forge jps-forge-index
docker-compose exec jps-forge jps-forge-forge

🎯 Quick Start

For detailed usage instructions, see the Usage Guide.

Basic workflow:

1. Install jps-forge (see above)
2. Configure workspace in ~/.config/jps-forge/config.yaml
3. Index your code: jps-forge-index
4. Start chatting: jps-forge-forge

📚 Documentation

• Usage Guide - Comprehensive usage instructions
• Development SOP - Development workflow
• Release SOP - Release procedures

🧰 Available Tools

The agent has access to the following tools:

• list_dirty_repos(): Find all git repositories with uncommitted changes
• current_repo_status(): Get git status of the current working directory
• git_status(repo_path): Get git status of a specific repository

For detailed usage examples, see the Usage Guide.

🧪 Development

See Development SOP for detailed development workflow.

Setup Development Environment

# Clone and install with dev dependencies
git clone https://github.com/jai-python3/jps-forge.git
cd jps-forge
pip install -e '.[dev]'

Run Tests

make test

Code Quality

# Auto-fix imports and formatting
make fix

# Format code with black
make format

# Run linting
make lint

Pre-commit Hooks

# Install pre-commit hooks
pre-commit install

# Run manually on all files
make precommit

📋 Requirements

• Python 3.10+
• Ollama (running locally)
• Git
• Required Python packages (installed automatically):
  • langchain
  • langchain-community
  • langchain-huggingface
  • langchain-ollama
  • langgraph
  • faiss-cpu
  • sentence-transformers
  • gitpython
  • rich
  • PyYAML

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📜 License

MIT License © Jaideep Sundaram

🙏 Acknowledgments

• Ollama for local LLM inference
• LangChain for the agent framework
• LangGraph for the ReAct agent implementation
• FAISS for vector similarity search
• Sentence Transformers for text embeddings

🔮 Roadmap

• Add more development tools (run tests, search code, refactor, etc.)
• Support for multiple programming languages
• Code modification and file creation capabilities
• Integration with more version control systems
• Custom tool plugins
• Web UI option
• Multi-repo workspace management

---

Note: This tool requires Ollama to be running. Make sure you have Ollama installed and at least one model pulled before using jps-forge.