AI-powered code quality platform with team rules, security scanning, and CI/CD integration. Your complete code gatekeeper.
npm install aico-aibash
npm install -g aico-ai
`
Project-Specific Installation:
`bash
npm install --save-dev aico-ai
`
$3
Prerequisites: You need a GitHub Personal Access Token with read:packages scope.
1. Configure npm to use GitHub Packages:
`bash
# Create .npmrc in your project or home directory
echo "@lukasddesouza:registry=https://npm.pkg.github.com" >> .npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> .npmrc
`
2. Install the package:
`bash
# Global installation
npm install -g @lukasddesouza/aico-ai
# Project installation
npm install --save-dev @lukasddesouza/aico-ai
`
๐ For detailed GitHub Packages setup instructions, see GITHUB_PACKAGES.md
$3
`bash
aico --version
`


---
Quick Start
$3
Run the interactive setup wizard:
`bash
aico init
`
This will guide you through:
- โ
Selecting your AI provider (Groq, OpenAI, DeepSeek, Ollama, Gemini)
- โ
Configuring your API key (or Ollama URL)
- โ
Choosing your preferred AI model
- โ
Setting up Git hooks (optional)
Example:
`
? Which AI provider would you like to use?
โฏ Groq (Fast & Free tier)
OpenAI (GPT-4o, etc.)
DeepSeek (Powerful & Cheap)
Ollama (Local & Private)
Google Gemini
? Enter your groq API Key: gsk_...
? Model name (default: llama-3.3-70b-versatile): [Enter]
? Would you like to setup Aico as a pre-push git hook? Yes
โ Configuration saved globally in ~/.aicorc for groq!
โ Husky pre-push hook configured!
`
$3
Initialize team-specific code quality standards:
`bash
aico rules init
`
This creates .aico/rules.json with sensible defaults. Customize it for your team:
`json
{
"version": "1.0",
"description": "Team code quality standards",
"rules": {
"forbidden": [
{
"pattern": "console\\.log",
"severity": "warn",
"message": "Remove console.log before committing"
}
],
"complexity": {
"maxFunctionLength": 50,
"maxCyclomaticComplexity": 10
},
"security": {
"noHardcodedSecrets": true,
"noEval": true
}
}
}
`
$3
`bash
Review your staged changes
git add .
aico review
Generate AI commit message
aico commit
Run security scan
aico security scan
Validate against team rules
aico rules validate
`
---
๐ Complete Command Reference
$3
#### aico init
Interactive setup wizard for configuring Aico.
`bash
aico init
`
What it does:
- Prompts for AI provider selection
- Configures API keys or Ollama URL
- Sets up preferred AI model
- Optionally configures Git hooks
---
#### aico review
AI-powered code review of staged changes.
`bash
aico review [options]
`
Options:
- --silent, -s: Run without blocking (non-interactive)
Example:
`bash
git add .
aico review
`
What it does:
- Analyzes git diff of staged changes
- Identifies bugs, security issues, code smells
- Suggests improvements with fix options
- Applies team rules validation
---
#### aico commit
Generate AI-powered commit messages.
`bash
aico commit
`
What it does:
- Analyzes staged changes
- Generates Conventional Commit message
- Allows editing, regeneration, or acceptance
- Commits with the final message
Example:
`bash
git add .
aico commit
Output:
Suggested message: feat(auth): add JWT token validation
#
What would you like to do?
โฏ Accept and commit
Edit message
Regenerate
Abort
`
---
$3
#### aico rules init
Initialize team rules configuration.
`bash
aico rules init
`
What it does:
- Creates .aico/rules.json with default template
- Includes examples for all rule types
- Ready to customize for your team
---
#### aico rules list
Display all active team rules.
`bash
aico rules list
`
Output:
`
๐ Team Rules Configuration
Version: 1.0
Total Rules: 15
Categories:
โข forbidden: 3 rule(s)
โข complexity: 4 rule(s)
โข security: 4 rule(s)
๐ซ Forbidden Patterns:
โ ๏ธ console\.log
Remove console.log before committing
โ debugger
Remove debugger statement before committing
`
---
#### aico rules validate
Validate staged changes against team rules.
`bash
aico rules validate
`
What it does:
- Checks staged files against all team rules
- Reports violations with severity levels
- Exits with code 1 if errors found (CI-friendly)
Example Output:
`
โ ๏ธ Found 3 rule violation(s):
src/index.js:
โ ๏ธ [WARN] Remove console.log before committing
Found 2 occurrence(s)
โ [ERROR] Potential hardcoded secret detected
โ ๏ธ [WARN] Function exceeds maximum length of 50 lines
Summary: 1 error(s), 2 warning(s)
`
---
$3
#### aico security scan
Full security scan (dependencies + code + configuration).
`bash
aico security scan [--output ]
`
Options:
- --output : Save report to JSON file
What it scans:
- Dependencies: npm/yarn/pnpm audit integration
- Code: 10+ vulnerability patterns
- Configuration: .env exposure, debug mode
Example:
`bash
aico security scan
Output:
๐ก๏ธ Security Scan Results
#
Dependencies:
โ lodash@4.17.15 - High Severity
CVE-2020-8203: Prototype Pollution
Fix: Update to lodash@4.17.21
#
Code Issues:
๐ด src/api.js:42
Potential SQL Injection
CWE-89
#
Summary: 3 vulnerabilities found (1 high, 2 moderate)
`
---
#### aico security check
Check specific security areas.
`bash
aico security check --dependencies # Check dependencies only
aico security check --code # Check code only
`
Use cases:
- Quick dependency checks in CI
- Code-only scans for pre-commit hooks
- Focused security audits
---
#### aico security report
Generate detailed security report.
`bash
aico security report
`
What it does:
- Performs full security scan
- Generates security-report.json
- Includes timestamp, summary, all vulnerabilities
- Provides recommendations
Report Structure:
`json
{
"timestamp": "2024-01-15T10:30:00Z",
"summary": {
"total": 5,
"critical": 1,
"high": 2,
"moderate": 2,
"low": 0
},
"dependencies": [...],
"codeVulnerabilities": [...],
"recommendations": [...]
}
`
---
$3
#### aico ci
Run in CI/CD mode with machine-readable output.
`bash
aico ci [options]
`
Options:
- --format : Output format (json, xml, github, text)
- --output : Save to file
- --fail-on-error: Exit 1 if errors found
- --fail-on-warn: Exit 1 if warnings found
- --severity : Filter by severity (error, warn, info)
Examples:
`bash
JSON output for parsing
aico ci --format json --output report.json
Fail pipeline on errors
aico ci --fail-on-error
GitHub Actions annotations
aico ci --format github
JUnit XML for CI tools
aico ci --format xml --output junit.xml
`
---
$3
#### aico help
Display help information.
`bash
aico help
`
#### aico --version
Display version number.
`bash
aico --version
`
---
๐ง Configuration
$3
Aico stores global settings in ~/.aicorc:
`json
{
"provider": "groq",
"providers": {
"groq": {
"apiKey": "gsk_...",
"model": "llama-3.3-70b-versatile"
},
"openai": {
"apiKey": "sk-...",
"model": "gpt-4o-mini"
},
"ollama": {
"baseUrl": "http://localhost:11434",
"model": "llama3"
}
}
}
`
$3
Override config with environment variables:
`bash
AI Provider API Keys
export GROQ_API_KEY="gsk_..."
export OPENAI_API_KEY="sk-..."
export DEEPSEEK_API_KEY="sk-..."
export GEMINI_API_KEY="..."
Provider Selection
export AICO_PROVIDER="groq"
`
$3
Project-specific code quality standards:
`json
{
"version": "1.0",
"description": "Team code quality standards",
"rules": {
"naming": {
"functions": "camelCase",
"classes": "PascalCase",
"constants": "UPPER_SNAKE_CASE"
},
"complexity": {
"maxFunctionLength": 50,
"maxCyclomaticComplexity": 10,
"maxNestingDepth": 4,
"maxFileLength": 500
},
"forbidden": [
{
"pattern": "console\\.log",
"severity": "warn",
"message": "Remove console.log before committing"
},
{
"pattern": "debugger",
"severity": "error",
"message": "Remove debugger statement"
},
{
"pattern": "TODO:|FIXME:",
"severity": "warn",
"message": "Unresolved TODO/FIXME found"
}
],
"required": [
{
"pattern": "^/\\\\[\\s\\S]?\\/\\s*function",
"severity": "warn",
"message": "Functions should have JSDoc comments"
}
],
"security": {
"noHardcodedSecrets": true,
"noEval": true,
"noInnerHTML": true,
"requireInputValidation": true
},
"teamStandards": {
"requireErrorHandling": true,
"requireTypeAnnotations": false,
"preferConst": true
}
},
"ignore": [
"*.test.js",
"*.spec.ts",
"dist/**",
"build/**"
]
}
`
---
Use Cases & Examples
$3
Setup:
`bash
aico init
Select "Yes" for Git hooks
`
Usage:
`bash
git add .
git push # Aico automatically reviews before push
`
What happens:
1. Aico intercepts the push
2. Reviews all staged changes
3. Shows issues and suggestions
4. Allows you to fix or proceed
---
$3
Setup:
`bash
aico rules init
Edit .aico/rules.json for your team
git add .aico/rules.json
git commit -m "chore: add team code quality rules"
`
Usage:
`bash
Before committing
aico rules validate
In CI/CD
aico rules validate || exit 1
`
Benefits:
- Consistent code quality across team
- Automated enforcement
- No manual code review for style issues
---
$3
Regular Security Scans:
`bash
Weekly security audit
aico security scan --output security-audit-$(date +%Y%m%d).json
Check for new dependency vulnerabilities
aico security check --dependencies
Pre-release security check
aico security scan
`
CI/CD Security Gate:
`yaml
.github/workflows/security.yml
- name: Security Scan
run: aico security scan
# Fails if critical/high vulnerabilities found
`
---
$3
GitHub Actions:
`yaml
name: Code Quality
on: [push, pull_request]
jobs:
quality-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install Aico
run: npm install -g aico-ai
- name: Run Code Review
env:
GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
run: |
git add -A
aico ci --format json --output report.json --fail-on-error
- name: Upload Report
if: always()
uses: actions/upload-artifact@v3
with:
name: code-quality-report
path: report.json
`
GitLab CI:
`yaml
code-quality:
stage: test
image: node:18
script:
- npm install -g aico-ai
- git add -A
- aico ci --format json --output report.json --fail-on-error
artifacts:
reports:
junit: report.xml
paths:
- report.json
only:
- merge_requests
- main
`
---
$3
Interactive Mode:
`bash
git add .
aico commit
Aico generates: "feat(auth): add JWT token validation"
You can: Accept, Edit, Regenerate, or Abort
`
Benefits:
- Consistent commit message format
- Saves time writing messages
- Follows Conventional Commits standard
- Context-aware descriptions
---
๐ Why Choose Aico?
$3
- โ
Team-First: Shared standards across all developers
- โ
IDE-Agnostic: Works with any editor
- โ
Git-Native: Integrates at the git level
- โ
Enforceable: Can block commits/pushes
$3
- โ
AI-Powered: Understands context and intent
- โ
Semantic Analysis: Beyond syntax checking
- โ
Security Scanning: Built-in vulnerability detection
- โ
Auto-Fix: AI suggests and applies fixes
$3
- โ
Lightweight: No server setup required
- โ
Fast: Local execution, instant feedback
- โ
Flexible: Multiple AI providers
- โ
Privacy: Local-first option with Ollama
---
Documentation
- Official Documentation - Visit our full documentation website
- Team Rules Guide - Complete guide to configuring team rules
- CI/CD Integration Guide - Detailed CI/CD setup instructions
- Product Roadmap - Upcoming features and priorities
- Issue Tracker - Report bugs or request features
---
Contributing
We welcome contributions! Whether it's:
- ๐ Bug Reports: Found an issue? Let us know!
- ๐ก Feature Requests: Have an idea? We'd love to hear it!
- ๐ Documentation: Help improve our docs
- ๐ง Code Contributions: Submit a pull request
Getting Started:
1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request
---
Supported AI Providers
| Provider | Speed | Cost | Privacy | Best For |
|----------|-------|------|---------|----------|
| Groq | โกโกโก | ๐ฐ Free tier | โ๏ธ Cloud | Fast, free reviews |
| OpenAI | โกโก | ๐ฐ๐ฐ Paid | โ๏ธ Cloud | High quality, GPT-4 |
| DeepSeek | โกโก | ๐ฐ Cheap | โ๏ธ Cloud | Cost-effective |
| Ollama | โก | ๐ฐ Free | ๐ Local | Privacy, offline |
| Gemini | โกโก | ๐ฐ Free tier | โ๏ธ Cloud | Google ecosystem |
---
Security & Privacy
- API Keys: Stored locally in ~/.aicorc (never committed)
- Code Privacy: Only diffs are sent to AI providers
- Local Option: Use Ollama for complete privacy
- No Telemetry: We don't collect any usage data
- Open Source: Audit the code yourself
---
License
ISC License - see LICENSE file for details
---
Acknowledgments
- Built with โค๏ธ by Lucas Silva
- Powered by AI providers: Groq, OpenAI, DeepSeek, Ollama, Gemini
- Inspired by the need for better code quality tools
---
Support
- ๐ง Email: projetos@codetechsoftware.com.br
- ๐ Issues: GitHub Issues
- ๐ฌ Discussions: GitHub Discussions
---
โญ Show Your Support
If you find Aico AI useful, please consider:
- โญ Starring the repository on GitHub - It helps others discover the project!
- ๐ Reporting bugs or ๐ก suggesting features via GitHub Issues
- ๐ข Sharing with your team and developer community
- ๐ค Contributing - We're open source and welcome contributions!
---
Contributing
We welcome contributions! Whether it's:
- ๐ Bug Reports: Found an issue? Let us know!
- ๐ก Feature Requests: Have an idea? We'd love to hear it!
- ๐ Documentation: Help improve our docs
- ๐ง Code Contributions: Submit a pull request
Getting Started:
1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request
Development Setup:
`bash
Clone your fork
git clone https://github.com/YOUR_USERNAME/aico-ai.git
cd aico-ai
Install dependencies
npm install
Test locally
node index.js --help
Make your changes and test
node index.js review
``