https://github.com/xavier2code/healix
Automated Self-Healing Software System — monitors logs, detects exceptions, generates fixes, and commits patches automatically
https://github.com/xavier2code/healix
Last synced: about 2 months ago
JSON representation
Automated Self-Healing Software System — monitors logs, detects exceptions, generates fixes, and commits patches automatically
- Host: GitHub
- URL: https://github.com/xavier2code/healix
- Owner: xavier2code
- Created: 2026-03-17T01:54:26.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-25T02:18:08.000Z (3 months ago)
- Last Synced: 2026-03-25T06:57:22.771Z (3 months ago)
- Language: TypeScript
- Size: 32.7 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Healix
Automated Self-Healing Software System
Healix monitors application logs, detects exceptions, locates problematic code, generates fixes, and commits patches automatically -- creating a complete closed-loop from error detection to code repair without human intervention.
## Badges
[](https://nodejs.org/)
[](https://nestjs.com/)
[](https://typescriptlang.org/)
[](https://docker.com/)
[](LICENSE)
[](#)
[](#)
## Features
- **Real-time Log Collection** -- Ingest logs from multiple sources (files, stdout, remote services)
- **Multi-language Exception Parsing** -- Supports Java, TypeScript/JavaScript, and Python stack traces
- **Stable Fingerprinting** -- SHA-256 based exception fingerprinting to track and deduplicate issues
- **Fault Localization** -- Map stack traces to precise source code locations
- **Fix Generation** -- Generate patches using templates, AST manipulation, and AI models
- **Docker-based Validation** -- Validate fixes in isolated containers before applying
- **VCS Integration** -- Automatic branch creation, commits, and PR/MR creation
- **Memory System** -- Persistent fix history to prevent duplicate fix attempts
## Quick Start
### Option 1: Docker (Recommended)
```bash
# Clone the repository
git clone https://github.com/xavier2code/healix.git
cd healix
# Start infrastructure + application with hot reload
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
```
Access at http://localhost:3000
### Option 2: Local Development
```bash
# Clone the repository
git clone https://github.com/xavier2code/healix.git
cd healix
# Install dependencies
npm install
# Build the project
npm run build
# Start infrastructure (PostgreSQL + Redis)
docker compose -f docker-compose.quickstart.yml up -d
# Run in development mode
npm run start:dev
```
## Architecture
The system follows an event-driven architecture where modules communicate via `EventEmitter2`:
1. **Log Collection** -- Monitors configured log sources and streams log lines
2. **Exception Detection** -- Identifies stack traces and extracts structured data
3. **Fingerprinting** -- Creates SHA-256 hash of type, message, and top stack frames
4. **Memory Check** -- Checks if exception has been seen before and its fix status
5. **Fault Localization** -- Maps stack frames to actual source code locations
6. **Fix Generation** -- Generates potential fixes based on exception context
7. **Validation** -- Tests fixes in isolated Docker containers
8. **VCS Integration** -- Commits validated fixes to a new branch
9. **PR Creation** -- Creates pull/merge request for human review
10. **Verification** -- Post-merge monitoring ensures the fix resolved the issue
## Modules
| Module | Description |
| -------------------- | -------------------------------------------------------------- |
| `log-collector` | Real-time log ingestion from files, stdout, and remote sources |
| `exception-parser` | Multi-language stack trace parsing (Java, TypeScript, Python) |
| `memory` | Exception fingerprinting, fix history, and deduplication |
| `fault-localization` | Map stack traces to source code locations |
| `fix-generation` | Generate patches using templates, AST, and AI |
| `validation` | Validate fixes in isolated Docker containers |
| `vcs-integration` | Git operations (branch, commit, push) |
| `pr-creation` | Create pull/merge requests on GitHub/GitLab |
| `verification` | Post-fix monitoring and automatic rollback |
## Requirements
- Node.js 18+
- Docker 20.10+ (required for containerized deployment and fix validation)
- Docker Compose v2+
### Optional (for local development without Docker)
- PostgreSQL 14+ (runs in-memory mode if not configured)
- Redis 6+ (runs without cache if not configured)
- Git
## Configuration
Copy `.env.example` to `.env` and configure:
```env
# Server
PORT=3000
NODE_ENV=development
# Database (optional)
DATABASE_URL=postgresql://healix:healix_dev@localhost:5432/healix
# Redis (optional)
REDIS_URL=redis://localhost:6379
# Docker (required for validation)
DOCKER_SOCKET=/var/run/docker.sock
# AI Provider (optional -- for LLM-based fix generation)
ANTHROPIC_API_KEY=sk-ant-your-key-here
# VCS Integration (optional)
GITHUB_TOKEN=ghp_your_token
GITLAB_TOKEN=glpat-your-token
```
## Docker Deployment
### Development Mode
```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
```
Features:
- Hot reload via volume mounts
- Source code mounted as read-only
- Debugging friendly
### Production Mode
```bash
docker compose -f docker-compose.yml -f docker-compose.prod.yml up --build
```
Features:
- Multi-stage build for small images (~200MB)
- Non-root user for security
- Resource limits (CPU/memory)
- Health checks enabled
- Restart policy
### Container Registry
The GitHub Actions workflow automatically builds and pushes images to `ghcr.io`:
```bash
# Pull latest
docker pull ghcr.io/xavier2code/healix:latest
# Run production
docker run -d --env-file .env -v /var/run/docker.sock:/var/run/docker.sock \
ghcr.io/xavier2code/healix:latest
```
See [docs/containerization.md](docs/containerization.md) for detailed documentation.
## Available Scripts
| Script | Description |
| -------------------- | ------------------------------------ |
| `npm run build` | Build the project |
| `npm run start` | Start the server |
| `npm run start:dev` | Start in development mode with watch |
| `npm run start:prod` | Start in production mode |
| `npm test` | Run all tests |
| `npm run test:watch` | Run tests in watch mode |
| `npm run test:cov` | Run tests with coverage |
| `npm run lint` | Lint and fix code |
| `npm run format` | Format code with Prettier |
## Supported Languages
| Language | Parser | Compiler | Fix Templates |
| ---------- | ------ | -------- | ------------- |
| TypeScript | Yes | Yes | Yes |
| JavaScript | Yes | Yes | Yes |
| Python | Yes | Yes | Yes |
| Java | Yes | Yes | Yes |
## Project Structure
```
healix/
├── src/
│ ├── main.ts # Application entry point
│ ├── app.module.ts # Root module
│ └── modules/
│ ├── exception-parser/ # Stack trace parsing
│ │ ├── parsers/ # Language-specific parsers
│ │ └── interfaces/ # Type definitions
│ ├── fault-localization/ # Source code mapping
│ ├── fix-generation/ # Patch generation
│ ├── log-collector/ # Log ingestion
│ ├── memory/ # Fingerprinting & history
│ │ ├── entities/ # TypeORM entities
│ │ ├── storage/ # Redis & PostgreSQL repos
│ │ └── interfaces/ # Type definitions
│ ├── pr-creation/ # PR/MR creation
│ ├── validation/ # Docker-based validation
│ │ └── compilers/ # Language-specific compilers
│ ├── vcs-integration/ # Git operations
│ └── verification/ # Post-fix monitoring
├── docs/ # Documentation
├── scripts/ # Utility scripts
├── package.json
├── tsconfig.json
├── nest-cli.json
├── Dockerfile # Multi-stage Docker build
├── docker-compose.yml # Base services (PostgreSQL, Redis)
├── docker-compose.dev.yml # Development profile
├── docker-compose.prod.yml # Production profile
└── docker-compose.quickstart.yml # Legacy quickstart
```
healix/
├── src/
│ ├── main.ts # Application entry point
│ ├── app.module.ts # Root module
│ └── modules/
│ ├── exception-parser/ # Stack trace parsing
│ │ ├── parsers/ # Language-specific parsers
│ │ └── interfaces/ # Type definitions
│ ├── fault-localization/ # Source code mapping
│ ├── fix-generation/ # Patch generation
│ ├── log-collector/ # Log ingestion
│ ├── memory/ # Fingerprinting & history
│ │ ├── entities/ # TypeORM entities
│ │ ├── storage/ # Redis & PostgreSQL repos
│ │ └── interfaces/ # Type definitions
│ ├── pr-creation/ # PR/MR creation
│ ├── validation/ # Docker-based validation
│ │ └── compilers/ # Language-specific compilers
│ ├── vcs-integration/ # Git operations
│ └── verification/ # Post-fix monitoring
├── docs/ # Documentation
├── scripts/ # Utility scripts
├── package.json
├── tsconfig.json
├── nest-cli.json
└── docker-compose.quickstart.yml
````
## Testing
```bash
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Generate coverage report
npm run test:cov
````
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
MIT License -- see [LICENSE](LICENSE) for details.
## Acknowledgments
- Built with [NestJS](https://nestjs.com/)
- AST parsing powered by [tree-sitter](https://tree-sitter.github.io/)
- AI fix generation by [Anthropic Claude](https://www.anthropic.com/)