repo-sapiens 0.5.2

Intelligent repository automation and management tool

repo-sapiens

The evolved, intelligent way to manage repositories

An AI-driven automation system for Git workflows with support for multiple AI agents, Git providers, and deployment modes.

Features

Implemented

• Multi-Platform Git Support: Works with GitHub, Gitea, and GitLab

  • Auto-detects provider from repository remote URL
  • GitHub Actions, Gitea Actions, or GitLab CI/CD workflow templates
  • Platform-specific API integration (including GitLab merge requests)

• Multiple AI Agent Support

  • Claude Code (claude-local): Anthropic's coding assistant CLI
  • Goose (goose-local): Block's flexible agent CLI with multiple LLM backends
  • Ollama (ollama): Local models (llama3.1, qwen3, codellama, deepseek-coder, etc.)
  • OpenAI-Compatible API (openai-compatible): Any OpenAI API-compatible service
    • Supports: OpenAI, Groq, OpenRouter, vLLM, LM Studio, Fireworks AI, Together AI, Anyscale, etc.
  • GitHub Copilot (copilot-local): Via unofficial proxy - see disclaimer
  • ReAct Agent: Built-in autonomous agent using any of the above backends
    • Interactive REPL mode with 9 built-in tools
    • Remote Ollama support for GPU servers
    • Path sandboxing for security

:warning: GitHub Copilot Disclaimer

The Copilot integration uses copilot-api, an unofficial, reverse-engineered API proxy. This integration:

• Is NOT endorsed or supported by GitHub
• May violate GitHub's Terms of Service
• Could stop working at any time without notice
• Should be used at your own risk

If you need a reliable, supported solution, use Claude Code, Goose, or OpenAI-compatible providers instead.

• Workflow Automation

  • Label-triggered workflows for issue processing
  • Development plan generation from issues
  • Task decomposition and execution
  • Automated code review
  • PR creation and management

• CLI Commands

  • sapiens init - Interactive repository setup with agent selection (GitHub/Gitea/GitLab)
  • sapiens task --repl - Interactive ReAct agent REPL
  • sapiens daemon - Run automation daemon
  • sapiens credentials - Manage credentials securely
  • sapiens process-issue - Process a specific issue
  • sapiens health-check - System health monitoring

• Developer Experience

  • 78% test coverage with 76 unit tests
  • Type hints throughout (mypy strict mode)
  • Pre-commit hooks for code quality
  • Comprehensive documentation

Quick Start

Installation

# Install from PyPI
pip install repo-sapiens

# Or install from source
git clone https://github.com/savorywatt/repo-sapiens.git
cd repo-sapiens
pip install -e ".[dev]"

Interactive Setup

# Initialize in your Git repository
sapiens init

This will:

• Auto-discover your Git repository configuration (GitHub, Gitea, or GitLab)
• Detect and select AI agent (Claude Code, Goose AI, or ReAct)
• Configure LLM provider settings
• Store credentials securely
• Generate configuration file
• Set up CI/CD workflow secrets

ReAct Agent REPL

Try the local AI agent with Ollama:

# Start interactive REPL (uses qwen3:latest by default)
sapiens task --repl

# Use a remote Ollama server
sapiens task --repl --ollama-url http://192.168.1.100:11434

# Use a specific model
sapiens task --repl --model codellama:13b

REPL commands:

• /help - Show available commands
• /models - List available Ollama models
• /model <name> - Switch to a different model
• /pwd - Show current working directory
• /verbose - Toggle verbose output
• /clear - Clear conversation history
• /quit - Exit REPL

Basic CLI Usage

# Process a specific issue
sapiens process-issue --issue 42

# Check system health
sapiens health-check

# Run as daemon
sapiens daemon --interval 60

# Manage credentials
sapiens credentials get @keyring:gitea/api_token

Configuration

Configuration File

Located at repo_sapiens/config/automation_config.yaml:

git_provider:
  provider_type: gitea  # or 'github', 'gitlab'
  base_url: ${GITEA_BASE_URL:-https://gitea.example.com}
  api_token: ${SAPIENS_GITEA_TOKEN}  # or SAPIENS_GITHUB_TOKEN, GITLAB_TOKEN

agent_provider:
  provider_type: ollama  # or 'claude-local', 'goose-local', 'openai-compatible'
  model: qwen3:latest  # or 'claude-sonnet-4.5', 'gpt-4', etc.
  base_url: http://localhost:11434  # for ollama or openai-compatible
  # api_key: ${API_KEY}  # only for openai-compatible

workflow:
  branching_strategy: per-agent
  max_concurrent_tasks: 3
  state_directory: .sapiens/state

Environment Variables

Override settings with AUTOMATION__ prefix (legacy) or SAPIENS__ prefix:

export AUTOMATION__GIT_PROVIDER__API_TOKEN="your-token"
export AUTOMATION__AGENT_PROVIDER__API_KEY="your-api-key"
export AUTOMATION__WORKFLOW__MAX_CONCURRENT_TASKS="5"

CI/CD Integration

Workflow Templates

The system includes workflow templates organized in .gitea/workflows/sapiens/:

Core Workflows:

Workflow	Description
automation-daemon.yaml	Periodic issue processing
process-issue.yaml	Process individual issues
needs-planning.yaml	Process issues labeled needs-planning
approved.yaml	Create tasks from approved plans
execute-task.yaml	Execute task implementations
needs-review.yaml	Automated code review
requires-qa.yaml	Run QA build and tests

Recipe Workflows (.gitea/workflows/sapiens/recipes/):

• daily-issue-triage.yaml - Automated issue triage
• weekly-test-coverage.yaml - Test coverage analysis
• weekly-dependency-audit.yaml - Dependency security audits
• weekly-security-review.yaml - Comprehensive security scans
• And more...

Repository Workflows (.gitea/workflows/):

• test.yaml - Run tests on PRs and pushes
• build-artifacts.yaml - Build and test package artifacts
• release.yaml - Release automation

Required Secrets

Configure in your repository settings:

Secret	Description
SAPIENS_GITEA_TOKEN	Gitea API token with repo access
SAPIENS_GITEA_URL	Gitea instance URL
SAPIENS_GITHUB_TOKEN	GitHub personal access token (for GitHub)
SAPIENS_GITLAB_TOKEN	GitLab personal access token (for GitLab)
SAPIENS_CLAUDE_API_KEY	Anthropic Claude API key

Architecture

repo_sapiens/
├── agents/           # ReAct agent implementation
│   ├── react.py      # ReAct loop and REPL
│   └── tools.py      # Agent tool definitions
├── cli/              # CLI commands
│   ├── init.py       # Interactive setup
│   └── credentials.py # Credential management
├── config/           # Configuration management
├── credentials/      # Credential backends (keyring, env, encrypted)
├── engine/           # Workflow orchestration
│   ├── orchestrator.py
│   ├── state_manager.py
│   └── stages/       # Workflow stages
├── git/              # Git operations and discovery
├── models/           # Domain models (Issue, Task, Plan)
├── providers/        # Git and AI providers
│   ├── gitea_rest.py
│   ├── github_rest.py
│   ├── gitlab_rest.py
│   ├── ollama.py
│   └── external_agent.py
├── rendering/        # Template rendering
├── templates/        # Jinja2 workflow templates
└── utils/            # Utilities

Development

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=repo_sapiens --cov-report=html

# Run specific test file
pytest tests/unit/test_react_agent.py -v

Code Quality

# Format code
black repo_sapiens/ tests/

# Lint code
ruff check repo_sapiens/ tests/

# Type check
mypy repo_sapiens/

# Run pre-commit hooks
pre-commit run --all-files

Docker

# Build and run with Docker Compose
docker-compose up -d

# Or build manually
docker build -t repo-sapiens .
docker run -it repo-sapiens --help

Documentation

Document	Description
Getting Started	Initial setup guide
Init Command Guide	Using sapiens init
Goose Setup	Goose AI configuration
Secrets Setup	CI/CD secrets configuration
CI/CD Usage	Workflow usage guide
Local Execution	Running locally
Gitea Tutorial	New Gitea repo setup
Architecture	System architecture
Error Handling	Error handling patterns
Deployment Guide	Production deployment
Developer Setup	Development environment setup
Contributing	Contribution guidelines
Changelog	Version history

Troubleshooting

Common Issues

Workflow doesn't trigger:

• Check Actions is enabled in repository settings
• Verify labels match workflow triggers
• Check runner is online

Permission errors:

• Verify API token has correct scopes
• Check repository permissions
• Ensure secrets are configured correctly

ReAct agent model not found:

• Pull the model: ollama pull qwen3:latest
• Check Ollama is running: curl http://localhost:11434/api/tags
• Verify --ollama-url is correct

Debug Mode

sapiens --log-level DEBUG process-issue --issue 42

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Before contributing, please:

1. Read the Contributor License Agreement
2. Sign off your commits with git commit -s
3. Ensure tests pass and code quality checks succeed

Links

• GitHub Repository: https://github.com/savorywatt/repo-sapiens
• Issue Tracker: https://github.com/savorywatt/repo-sapiens/issues
• PyPI Package: https://pypi.org/project/repo-sapiens/

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Maintained by @savorywatt