cli

Context Vibes CLI

Context Vibes is a command-line tool designed to streamline common development tasks and generate context for AI assistants. It provides consistent wrappers for Git workflows, Infrastructure as Code (IaC) operations, code quality checks, formatting, testing, and programmatic code modifications, focusing on clear, structured terminal output and detailed background logging.

Why Context Vibes?

• Consistency: Provides a unified interface and terminal output style for frequent actions (commit, sync, deploy, etc.).
• Automation: Simplifies multi-step processes and provides non-interactive options via the global --yes flag. Designed for use in scripts or by AI agents.
• AI Integration:
  • Generates a contextvibes.md context file (describe, diff) suitable for AI prompts.
  • Produces structured terminal output (using SUMMARY:, INFO:, ERROR:, ADVICE:, and status prefixes like +, -, ~, !) suitable for human review or direct AI parsing.
  • Generates a detailed JSON trace log (default: contextvibes.log, configurable) for deeper AI analysis or debugging, separate from terminal output.
• Clarity & Safety: Uses distinct output formats for different information types and requires confirmation for state-changing operations (unless --yes is specified).
• Configurability: Supports a .contextvibes.yaml file in the project root for customizing default behaviors like Git branch/remote names, validation patterns, and default log file names.

Key Features

• AI Context Generation:
  • describe: Gathers project details (env, git status, files, user prompt) into contextvibes.md. Supports -o for output file customization. Respects .gitignore and .aiexclude.
  • diff: Summarizes pending Git changes (staged, unstaged, untracked), overwriting contextvibes.md.
• Git Workflow Automation (Configurable branch/commit rules):
  • kickoff: Start-of-work routine (update main, create/switch new work branch). Requires confirmation. Branch name validation configurable (default pattern: ^((feature|fix|docs|format)/.+)$).
  • commit: Stages all changes and commits locally. Requires -m <message> flag. Requires confirmation. Commit message format validation configurable (default pattern uses Conventional Commits: ^(BREAKING|feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-zA-Z0-9\-_]+\))?:\s.+).
  • sync: Updates local branch from remote (pull --rebase) and pushes if ahead. Requires clean state and confirmation.
  • wrapup: End-of-day routine (stages all, commits with default message if needed, pushes). Requires confirmation.
  • status: Shows concise git status --short output.
• Infrastructure as Code (IaC) Wrappers:
  • plan: Run terraform plan -out=tfplan.out or pulumi preview.
  • deploy: Run terraform apply tfplan.out or pulumi up. Requires confirmation.
  • init: Run terraform init (primarily for Terraform projects).
• Code Quality & Formatting:
  • quality: Run formatters (in check mode), validators, and linters (Terraform, Python, Go support included).
  • format: Apply code formatting (go fmt, terraform fmt, isort, black) modifying files in place.
• Project Testing & Versioning:
  • test: Runs project-specific tests (e.g., go test ./..., pytest). Arguments are passed to the underlying test runner.
  • version: Displays the CLI version.
• Code Modification:
  • codemod: Applies programmatic code modifications or deletions from a JSON script (default script: codemod.json).

Installation

Ensure you have Go (1.24 or later recommended) and Git installed.

1. Install using go install:

   go install github.com/contextvibes/cli/cmd/contextvibes@latest
   

   Installs to $GOPATH/bin (usually $HOME/go/bin).

2. Ensure Installation Directory is in your PATH:

   # Add one of these to your shell profile (.bashrc, .zshrc, etc.)
   export PATH=$(go env GOPATH)/bin:$PATH
   # Or: export PATH=$HOME/go/bin:$PATH
   

   Restart your shell or source the profile (source ~/.bashrc).

(Alternative) Installation via Releases: Download from GitHub Releases (Adjust URL when releases are available), make executable (chmod +x), move to a directory in your PATH.

Dependencies: Relies on external tools being in your PATH: git, and depending on project type and commands used: terraform, pulumi, tflint, isort, black, flake8, go (for Go project commands), python (for Python project commands).

Important: Ignoring Generated Files

contextvibes generates files such as:

• contextvibes.md (default output for describe and diff commands)
• contextvibes.log (the default AI trace log file if not configured otherwise)
• tfplan.out (by the plan command when used with Terraform projects)

It is strongly recommended to add these generated files to your project's .gitignore file to prevent them from being tracked by version control. Tracking these files can lead to unnecessary merge conflicts, large repository sizes, and may break certain CI/CD or build tasks.

Example entries for your project's .gitignore:

# Files generated by contextvibes and related tools
contextvibes.md
contextvibes.log  # Default AI trace log
contextvibes_ai_trace.log # Common alternative if customized

# Generic log files (if you customize the AI log name further)
# or other logs your project might produce.
*.log

# Terraform plan files (if using contextvibes with Terraform)
tfplan.out
*.tfplan

# Default codemod script name if you check it in but want to ignore local versions
# codemod.json # Consider if you want to ignore this by default

You can customize the names and locations of some of these files using command-line flags (e.g., -o for describe, --ai-log-file for the trace log) or via the .contextvibes.yaml configuration file (e.g., logging.defaultAILogFile). Ensure your .gitignore rules cover your chosen names and paths. For instance, if you configure contextvibes to output its AI log to project_logs/ai_trace.log, a rule like project_logs/ or *.log would be appropriate.

Usage

contextvibes [command] --help  # General help or help for a specific command
contextvibes [command] [flags] # Run a command

Common Flags:

• -y, --yes: Assume 'yes' to all confirmation prompts. Useful for scripts and automation.
• --ai-log-file <path>: Specify a file path for the detailed AI JSON log (overrides config default).
• --log-level-ai <level>: Set the minimum level for the AI log file (debug, info, warn, error; default: debug).

Examples:

# Start a new feature branch (prompts for name if not provided via --branch)
contextvibes kickoff --branch feature/add-user-auth

# Describe the project for an AI (prompts for task description)
contextvibes describe -o my_context.md

# Show pending Git changes (overwrites contextvibes.md)
contextvibes diff

# Apply code formatting
contextvibes format

# Check code quality
contextvibes quality

# Run project tests (e.g., for a Go project, passing -v flag)
contextvibes test -v

# Plan infrastructure changes
contextvibes plan

# Commit work (message required, interactive confirmation)
contextvibes commit -m "feat(auth): Implement OTP login"

# Commit work (non-interactive)
contextvibes commit -m "fix(api): Correct typo in user model" -y

# Sync with remote (requires confirmation)
contextvibes sync

# Sync non-interactively
contextvibes sync -y

# End your day (requires confirmation)
contextvibes wrapup

# End your day non-interactively
contextvibes wrapup -y

# Display CLI version
contextvibes version

# View command options
contextvibes commit --help

# Apply programmatic changes from a script (default: codemod.json)
contextvibes codemod
contextvibes codemod --script ./changes.json

Terminal Output vs. AI Log File

Context Vibes uses two distinct output mechanisms:

1. Terminal Output (stdout/stderr):
   • Designed for human readability and potential AI parsing of the command's outcome and context.
   • Uses structured blocks (SUMMARY:, INFO:, ERROR:, ADVICE:) and status prefixes (+, -, ~, !).
   • stdout generally contains status information, results, and advice.
   • stderr contains operational errors and interactive prompts (like confirmation).
2. AI Log File (JSON):
   • Written to contextvibes.log by default (configurable via .contextvibes.yaml or --ai-log-file).
   • Contains a detailed, structured trace of the command's internal execution steps, parameters, and outcomes using slog.
   • Intended for deeper analysis by AI agents or for debugging by humans.
   • Log level controlled by --log-level-ai (defaults to debug).

Configuration (.contextvibes.yaml)

contextvibes can be configured using a .contextvibes.yaml file placed in the root of your project. This allows for project-specific settings that can be version-controlled. If the file is not present, the CLI uses sensible built-in defaults.

Example .contextvibes.yaml:

# Git settings
git:
  defaultRemote: origin
  defaultMainBranch: main # or master, develop, etc.

# Logging settings
logging:
  defaultAILogFile: "logs/contextvibes_ai.log" # Path relative to project root

# Validation rules
validation:
  branchName:
    enable: true  # Default is true. Set to false to disable validation.
    # Default pattern if enabled and not specified: ^((feature|fix|docs|format)/.+)$
    # pattern: "^(feature|fix|chore|task)/[A-Z]+-[0-9]+-.*$" # Example custom pattern
  commitMessage:
    enable: true # Default is true. Set to false to disable validation.
    # Default pattern if enabled and not specified: ^(BREAKING|feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-zA-Z0-9\-_]+\))?:\s.+
    # pattern: "^(feat|fix|chore|docs)!?(\\(.+\\))?: .+" # Example custom pattern

• If a pattern is not specified for an enabled validation rule, the CLI's built-in default pattern (as shown in comments above) will be used.
• The --ai-log-file CLI flag will always override the logging.defaultAILogFile setting from the configuration file. The ultimate fallback if no configuration is set for the AI log file is contextvibes.log.

Note on AI Context Files (contextvibes.md, .idx/airules.md, .aiexclude)

• contextvibes.md (Generated by describe/diff): Dynamic snapshot of project state/diff + user prompt. Use this as the input prompt for external AI models.
• .idx/airules.md (IDE Config): Static configuration for IDE-native AI features (e.g., Project IDX). contextvibes currently reads but does not generate this (see Roadmap).
• .aiexclude (Exclusion Rules): User-defined rules (like .gitignore) to exclude files/dirs from describe.

Contributing

Please see CONTRIBUTING.md for guidelines. Key areas include adding unit tests, refactoring remaining non-Git commands, and updating documentation.

Code of Conduct

Act professionally and respectfully. Be kind, considerate, and welcoming. Harassment or exclusionary behavior will not be tolerated.

Related Files

• CHANGELOG.md: Tracks notable changes.
• CONTRIBUTING.md: Contribution guidelines, known issues/TODOs.
• ROADMAP.md: Future plans.

License

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