AICockpit - AI Harness Engineering Platform

O AICockpit é o sistema operacional local definitivo para IAs autônomas. Ele amplifica as capacidades do seu Agente de IA favorito (como Antigravity, Devin ou Claude), fornecendo um Cofre Seguro (Vault) nativo, um Dashboard Visual para humanos colaborarem com a IA, e um Gerenciador de Habilidades (Packages) integrado.

---

🚀 1. Instalação e Setup Inicial

Comece instalando a CLI localmente (requer Go 1.26+):

# 1. Instale o AICockpit via Go
go install github.com/lleitep3/aicockpit@latest

# 2. Rode o setup interativo (Selecione sua IA preferida, ex: Antigravity)
cockpit setup

📦 2. Adicione o Registry Oficial

O ecossistema do Cockpit é extensível. Conecte-se ao registry oficial para ter acesso às melhores ferramentas e habilidades:

cockpit pkg registry add default https://github.com/lleitep3/cockpit-registry

🛠️ 3. Instale os Módulos Essenciais

Para uma experiência completa (incluindo interface visual e gestão de tarefas Kanban), instale os pacotes e utilize os recursos nativos:

# Instale a interface visual interativa (UI)
cockpit pkg install cockpit-dashboard

(Nota: O gerenciador Kanban cockpit project já é nativo no core da CLI!)

🤖 4. Trabalhe Junto com a IA

Agora sua infraestrutura está pronta! Abra o terminal, inicie sua IA (como Antigravity ou Devin) e trabalhe de forma integrada:

Você: "IA, use o cockpit project para criar uma nova tarefa para refatorar o login. Depois abra o dashboard visual."

A IA irá utilizar automaticamente as habilidades locais que você instalou e interagir com o Cofre Seguro do seu sistema operacional, sem precisar expor chaves de API em texto plano!

---

📚 Documentação e Arquitetura

Getting Started

• Quick Start Guide - Get up and running in 5 minutes
• Installation Guide - Detailed installation instructions
• Installation Scripts - How the installation scripts work
• Installation Options - User-level vs System-wide installation

Features & Usage

• Features Overview - Complete list of features and capabilities
• Logging & Metrics - How to use the logging and metrics system
• Metrics Command Verification - Verify metrics command is working

Development

• Contributing Guide - How to contribute to AICockpit
• AI Agent Guidelines - Comprehensive guide for AI agents developing on AICockpit
• CI/CD Pipeline - CI/CD workflow and automation details
• SDLC Guidelines - Software Development Lifecycle standards

Project Information

• Executive Summary - High-level project overview
• Implementation Summary - Phase 1 implementation details
• Session Summary - Latest session summary
• Global Installation Verified - Installation verification

💻 Developer Installation (From Source)

Prerequisites

• Go 1.26 or later
• Linux, macOS, or Windows
• Git

Linux/macOS

Option 1: User-Level Installation (Recommended)

# Clone the repository
git clone git@github.com:lleitep3/aicockpit.git
cd aicockpit

# Build and install (automatic PATH configuration)
make install

# Verify installation
cockpit --version

Option 2: System-Wide Installation (Global)

# Build and install globally (requires sudo)
make install-global

# Verify installation
cockpit --version

Windows

# Build and install
make install-win

# Verify installation
cockpit --version

Initial Setup

# Run setup wizard
cockpit setup

# Check system health
cockpit doctor

# View configuration
cockpit info

For more details, see Quick Start Guide.

📋 Referência de Comandos

Core Commands

• cockpit setup - Interactive setup wizard

  • Select language (English, Portuguese)
  • Choose AI provider (Claude, GPT, Devin, Antigravity, Goose)
  • Initialize vault and configuration

• cockpit info - Display AICockpit information

  • Show current configuration
  • List installed packages
  • Display file locations

• cockpit doctor - Health check

  • Verify all components are properly configured
  • Check directory structure
  • Validate configuration files

• cockpit uninstall - Remove AICockpit

  • Safely uninstall and remove all data

Metrics & Analytics

• cockpit metrics list - View execution metrics

  • Filter by command, status, or date
  • Limit results
  • View all command executions

• cockpit metrics stats - Show execution statistics

  • Total executions and success rate
  • Average duration
  • Command frequency
  • Error types

• cockpit metrics logs - View log files

  • List all log files
  • View logs for specific date
  • Check log file details

Security & Secrets

• cockpit vault set - Store a secret securely in the OS Keyring
• cockpit vault get - Retrieve a secret
• cockpit vault remove - Remove a secret

Packages & Extensibility

• cockpit pkg install - Install a new package (e.g. cockpit-dashboard)
• cockpit pkg search - Search for available packages in registries
• cockpit pkg upgrade - Upgrade installed packages
• cockpit pkg registry - Manage multiple package registries

Project & Task Management

• cockpit project sync - Sync local tasks bi-directionally with GitHub Issues
• cockpit project add - Create a new task in the Kanban board
• cockpit project move - Change the state of a task (todo, in_progress, done)

Assistant

• cockpit ask "<task>" - Run one assistant turn (memory recall, a claude, codex, or API worker, streamed output, and retain). See cockpit ask.

Planned Commands

• cockpit agent - Not a command. Run a task with cockpit ask (product vision)
• cockpit skills - Manage skills explicitly
• cockpit rules - Manage rules explicitly

🌍 Internationalization

AICockpit supports multiple languages:

• English (en-us)
• Portuguese Brazilian (pt-br)

Set language globally:

cockpit --language pt-br info

📁 Directory Structure

AICockpit creates the following structure in ~/.cockpit/:

~/.cockpit/
├── config.yaml          # Configuration file
├── metrics.json         # Execution metrics
├── logs/                # Log files (daily rotation)
│   ├── cockpit-2026-06-20.log
│   ├── cockpit-2026-06-21.log
│   └── ...
├── cache/               # Cache directory
├── packages/            # Installed packages
├── vault/               # Secrets vault
├── agents/              # AI agents
├── skills/              # Skills
├── rules/               # Rules
├── hooks/               # Hooks
└── kb/                  # Knowledge bases

🔧 Development

Build Commands

make help              # Show all available commands
make build             # Build the binary
make test              # Run tests with coverage
make lint              # Run linters
make fmt               # Format code
make check             # Run all checks
make clean             # Clean build artifacts
make install-hooks     # Install git pre-commit hooks

🧑‍💻 Identity File

AICockpit supports a local identity.md file to store your personal developer profile, workspace preferences and AI communication conventions.

• Use internal/assets/default_cockpit/identity-example.md as a starting point.
• Copy it to identity.md and update your own name, role, location, stack and workflow preferences.
• identity.md is ignored by Git to keep personal identity data local.

Project Structure

aicockpit/
├── cmd/                    # CLI commands
│   ├── setup.go
│   ├── info.go
│   ├── doctor.go
│   ├── uninstall.go
│   ├── metrics.go
│   └── root.go
├── internal/               # Internal packages
│   ├── config/            # Configuration management
│   ├── logger/            # Logging system (deprecated)
│   ├── i18n/              # Internationalization
│   └── logging/           # New logging & metrics system
├── scripts/                # Installation scripts
│   ├── install.sh         # Linux/macOS installer
│   └── install.ps1        # Windows installer
├── .github/                # GitHub configuration
│   ├── workflows/         # GitHub Actions
│   └── PULL_REQUEST_TEMPLATE.md
├── docs/                   # Documentation
├── main.go                 # Entry point
├── Makefile                # Build automation
├── CONTRIBUTING.md         # Contribution guidelines
└── README.md               # This file

Testing

# Run all tests
make test

# Run specific package tests
go test -v ./internal/config

# View coverage report
go tool cover -html=coverage.out

📊 Code Quality

• Linting: go vet and golangci-lint
• Testing: Unit tests with ≥90% coverage target (current: 68.0% — work in progress)
• Formatting: go fmt compliance
• Documentation: Comprehensive guides and examples
• CI/CD: GitHub Actions for automated validation

🔐 Security

• Secrets are stored in OS keyrings (planned)
• All operations are logged
• Configuration is user-specific
• No sensitive data in logs
• Pre-commit hooks validate code quality

📊 Logging & Metrics

AICockpit automatically tracks all command executions with detailed metrics:

# View execution metrics
cockpit metrics list

# View statistics
cockpit metrics stats

# View log files
cockpit metrics logs

# Filter by command
cockpit metrics list --command setup

# Filter by status
cockpit metrics list --status error

# Filter by date
cockpit metrics list --date 2026-06-20

Features:

• Daily log rotation (cockpit-YYYY-MM-DD.log)
• JSON format for easy parsing
• Automatic metrics collection
• Success/failure tracking
• Performance metrics
• Error analysis

See Logging & Metrics Documentation for details.

🤝 Contributing

We welcome contributions! Please follow these guidelines:

1. Read the Contributing Guide - Important guidelines and standards
2. Semantic Commits - Use conventional commit format
3. PR Requirements - Include [MAJOR], [MINOR], or [PATCH] in PR title
4. Tests - Write tests for new features
5. Quality - Run make check before committing

Quick Contribution Steps

# 1. Fork and clone
git clone git@github.com:YOUR_USERNAME/aicockpit.git
cd aicockpit

# 2. Create feature branch
git checkout -b feature/your-feature

# 3. Install pre-commit hooks
make install-hooks

# 4. Make changes and commit
git add .
git commit -m "feat(scope): description"

# 5. Run checks
make check

# 6. Push and create PR
git push origin feature/your-feature

📄 License

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

🙋 Support

For issues, questions, or suggestions:

1. Check existing issues
2. Create a new issue
3. Join discussions

🗺️ Roadmap

Phase 1 ✅ (Complete)

• ✅ Core CLI structure
• ✅ Configuration system
• ✅ Logging, Metrics, and i18n
• ✅ Installation scripts (user-level & system-wide)

Phase 2 ✅ (Complete)

• ✅ Vault system (keyring integration)
• ✅ Package management (cockpit pkg and registries)
• ✅ Project management (Kanban & GitHub Sync)
• ✅ Visual Dashboard (SvelteKit/FastAPI)
• ✅ Knowledge base search (BM25 + Graph Traversal)

Phase 3 (In Progress)

• Agent management system
• Skills and rules framework
• Hooks system
• Advanced metrics & token analytics

Phase 4 (Vision)

• AI-powered autonomous optimization
• Performance and cost analysis trends

📈 Project Statistics

• Total Commits: 120+
• Lines of Code: 28000+
• Lines of Documentation: 18000+
• Test Coverage: 68.0%
• Tests Passing: 737/737 in 12 packages ✓

🎓 Learn More

For Users

• Quick Start Guide - Get started quickly
• Installation Guide - Detailed setup instructions
• Features Overview - All available features
• Logging & Metrics - How to use metrics

For Developers

• Contributing Guide - How to contribute
• SDLC Guidelines - Development standards
• AI Agent Guidelines - For AI agents working with AICockpit

For Project Managers

• Executive Summary - High-level overview
• Implementation Summary - Phase 1 details
• Session Summary - Latest work summary

🙌 Acknowledgments

AICockpit is built with:

• Go - Programming language
• Cobra - CLI framework
• GitHub Actions - CI/CD

📞 Contact

• GitHub: lleitep3/aicockpit
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for AI systems everywhere

Knowledge Base (KB)

• KB Guides - Explore all available AICockpit CLI guides
• Package Manager Guide
• Canonical Compiler Architecture