#Author: Miker Seetoo #No I will not be changing the name

codesex Documentation

codesex is a zero-dependency, DevSecOps automation tool designed to analyze Git diffs and generate artifacts. By hooking directly into local LLMs or cloud providers, it automates code reviews, technical documentation updates, security vulnerability tracking, and dynamic risk scoring before code hits your production pipeline.

Architecture

1. Installation

Install the package into your project as a development dependency:

npm install --save-dev codesex

Or you can run commands directly without a persistent installation using npx:

npx codesex --help

2. Initialization

Generate a fresh template configuration file in the root directory of your project:

npx codesex init

This creates a codesex.json file.

Configuration (codesex.json)

The config file manages your connection strings, controls which automated tasks execute, and allows you to rewrite the base system prompt instructions to your liking.

{
  "apiKey": "",
  "baseUrl": "https://api.openai.com/v1",
  "model": "gpt-4o-mini",
  "outputDir": "artifacts",
  "tasks": [
    "docs",
    "review",
    "security"
  ],
  "plugins": [],
  "prompts": {
    "docs": "Generate technical docs for changed code",
    "review": "Review for bugs, maintainability, performance, and logic errors.",
    "security": "Perform devsecops review focusing on secrets, auth, injection, and insecure config."
  }
}

Environment Overrides

To protect secrets or dynamically configure pipelines, codesex prioritizes environment variables over standard JSON properties:

| JSON Key | Environment Variable | Purpose | | --- | --- | --- | | apiKey | AI_API_KEY | Bearer Token authentication credential | | baseUrl | AI_BASE_URL | Destination host URI path for API endpoint calls | | model | AI_MODEL | Explicit text generation model identifier | | outputDir | SECS_OUTPUT_DIR | Name of the local output workspace directory |

CLI Commmands

codesex includes an expressive CLI to drive individual tasks or run unified evaluations.

codesex run

Analyzes your current local Git changes (prioritizing staged files, fallback to your last commit) and simultaneously runs all active background validation jobs.

npx codesex run

codesex init

This will initialize the default codesex.json file

npx codesex init

codesex doctor

This will show you the env variables you have initialized

npx codesex doctor

codesex serve

This will launch a server on localhost:4321 with a dashboard of your codesex artifacts. This is still a work in progress.

npx codesex serve

codesex compare [base] [head]

Explicitly focuses the AI evaluation on changes strictly occurring between two specified branches, commits, or tags.

npx codesex compare main feature-branch

codesex review-pr <provider> <repo_id> <pr_id>

Executes code evaluation against your active codebase changes and directly posts a summary comment to your pull request/merge request thread.

• Supported Providers: github | gitlab

npx codesex review-pr github octocat/hello-world 42

codesex document

Runs the document function individually. Generates an ai-doc.md

npx codesex document

codesex risk

Runs the risk report individually. Generates risk-report.json

npx codesex risk

codesex security

Runs security check individually. Generates ai-security-report.md

npx codesex security

codesex review

Runs review function individually. Generates ai-pr-review.md

npx codesex review

codesex --help

Take a guess

npx codesex --help

Generated Artifacts

When executing codesex run, the workspace builds isolated files inside your assigned output directory (defaulting to ./artifacts):

• changed-files.txt: A clean, newline-separated catalog of target source files parsed.
• ai-docs.md: Freshly structured developer documentation capturing functional architectural adjustments.
• ai-pr-review.md: Pragmatic peer review logging code quality findings, structural feedback, and optimizations.
• ai-security-report.md: Meticulous DevSecOps threat assessment searching for vulnerabilities, injection vectors, or leaked credentials.
• risk-score.json: Structural metadata parsing code impact strictly conforming to this scheme:

{
  "score": 35,
  "summary": "Mild refactor introducing standard error handling logic.",
  "highlights": ["Adds comprehensive try/catch blocks to core data router"]
}

Testing Locally via Ollama

You can completely detach codesex from proprietary models and run your DevSecOps pipeline entirely on your local machine for zero cost with Ollama.

1. Boot up Ollama locally and fetch a small model explicitly tuned for code analysis:

ollama pull qwen2.5-coder:1.5b

2. Run codesex by passing variables targeting your local engine instance:

AI_API_KEY="local-bypass" \
AI_BASE_URL="http://localhost:11434/v1" \
AI_MODEL="gemma4" \
npx codesex run

CI/CD Integration (GitHub Actions)

Add codesex into your testing suite using local CPU-bound workflows to validate commits automatically without exposing API keys:

name: codesex

on:
  pull_request:
    branches: [ main ]

jobs:
  security-audit:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Essential to compute accurate git diff targets

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Setup Ollama
        uses: ai-action/setup-ollama@v2

      - name: Pull Evaluation Model
        run: ollama pull gemma4

      - name: Run codesex Pipeline
        env:
          AI_API_KEY: "ollama-bypass"
          AI_BASE_URL: "http://localhost:11434/v1"
          AI_MODEL: "gemma4"
          SECS_OUTPUT_DIR: "devsecops-artifacts"
        run: |
          npm ci
          npx codesex run
        
      - name: Archive DevSecOps Build Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: devsecops-ai-reports
          path: devsecops-artifacts/
          retention-days: 14

flowchart TD
    Trigger((Pull Request <br/> to 'main')) --> Job[Job: security-audit <br/> Environment: ubuntu-latest]
    
    subgraph Execution Steps
        direction TB
        Job --> S1[Checkout Repository <br/> actions/checkout@v4]
        S1 --> S2[Setup Node.js <br/> Version 20]
        S2 --> S3[Setup Ollama <br/> ai-action/setup-ollama@v2]
        S3 --> S4[Pull Evaluation Model <br/> gemma4]
        S4 --> S5[Run codesex Pipeline <br/> npm ci & npx codesex run]
        S5 --> S6[Archive Artifacts <br/> actions/upload-artifact@v4]
    end

    %% Additional Context / Environment details
    S5 -. Injects Env Vars .-> Env[AI_API_KEY <br/> AI_BASE_URL <br/> AI_MODEL <br/> SECS_OUTPUT_DIR]
    S6 -. Saves Path .-> Art[devsecops-artifacts/ <br/> Retention: 14 days]

CI/CD Integration (GitLab Pipeline)

stages:
  - test

variables:
  AI_API_KEY: "ollama-bypass"
  AI_BASE_URL: "http://localhost:11434/v1"
  AI_MODEL: "gemma3"
  SECS_OUTPUT_DIR: "devsecops-artifacts"

security-audit:
  stage: test
  image: node:20  # Node 20 provides the environment for npx
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main"'
  before_script:
    - apt-get update && apt-get install -y zstd curl
    - curl -fsSL https://ollama.com/install.sh | sh
    - ollama serve &
    - sleep 5
    - ollama pull gemma3
  script:
    - npx codesex run
  artifacts:
    name: "devsecops-ai-reports"
    paths:
      - devsecops-artifacts/
    expire_in: 14 days

flowchart TD
    Trigger((Merge Request Event <br/> Target Branch: 'main')) --> Job[Job: security-audit <br/> Image: node:20]
    
    subgraph Execution Steps
        direction TB
        Job --> S1[before_script: <br/> Install curl & zstd]
        S1 --> S2[Install Ollama <br/> via install.sh]
        S2 --> S3[Start Ollama <br/> ollama serve &]
        S3 --> S4[Pull Evaluation Model <br/> ollama pull gemma3]
        S4 --> S5[script: <br/> npx codesex run]
        S5 --> S6[Upload Artifacts <br/> devsecops-artifacts/]
    end

    %% Pipeline Variables and Artifact Retention
    S5 -. Injects Variables .-> Var[AI_API_KEY <br/> AI_BASE_URL <br/> AI_MODEL <br/> SECS_OUTPUT_DIR]
    S6 -. Saves Path .-> Art[devsecops-artifacts/ <br/> Expire: 14 days]

CI/CD Integration (Env Variables)

If you want to use your own model, just set your keys in the codesex.json. You can also set the variables in your CI/CD settings. Use the following naming convention

AI_API_KEY AI_BASE_URL AI_MODEL

The package will default to these env variables over whatever you have in your codesex.json

stages:
  - test
variables:
  SECS_OUTPUT_DIR: "devsecops-artifacts"

security-audit:
  stage: test
  image: node:20  # Node 20 provides the environment for npx
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main"'
  script:
    - npx codesex run
  artifacts:
    name: "devsecops-ai-reports"
    paths:
      - devsecops-artifacts/
    expire_in: 14 days

flowchart TD
    Trigger((Merge Request Event <br/> Target Branch: 'main')) --> Job[Job: security-audit <br/> Image: node:20]
    
    subgraph GitLab CI/CD Runtime
        Job --> RunScript[script: <br/> npx codesex run]
    end

    subgraph Config Resolution Logic [How codesex Decides Which Config to Use]
        RunScript --> CheckEnv{Are Env Variables Set? <br/> AI_API_KEY <br/> AI_BASE_URL <br/> AI_MODEL}
        
        CheckEnv -- Yes --> UseEnv[Priority 1: Environment Variables <br/> Override config file values]
        CheckEnv -- No --> UseConfig[Priority 2: codesex.config.json <br/> Fallback to local defined values]
    end

    subgraph Outputs
        UseEnv --> Exec[Execute Security Audit]
        UseConfig --> Exec
        Exec --> S2[Upload Artifacts <br/> devsecops-artifacts/]
    end

    S2 -. Saves Path .-> Art[devsecops-artifacts/ <br/> Expire: 14 days]

Custom Plugins

codesex features an extensible runtime wrapper allowing you to run bespoke logic right alongside the core engine. To design a plugin, export an default object matching the runtime interface structure:

// plugins/license-check.js
import fs from 'node:fs';
import path from 'node:path';

export default {
    name: "license-check",
    async run({ diff, changedFiles, outputDir }) {
        // Custom verification checking for restricted dependency ingestion
        if (diff.includes("gpl-3.0")) {
             fs.writeFileSync(
                 path.join(outputDir, "plugin-license-alert.txt"), 
                 "ALERT: GPL-3.0 string sequence detected inside incoming code modifications."
             );
        }
    }
};

Register the file inside your codesex.json array:

"plugins": [
  "./plugins/license-check.js"
]