Nexus

Nexus is a comprehensive OpenCode plugin that provides a powerful suite of eight integrated modules to manage your development lifecycle. From token budgets and persistent memory to multi-agent orchestration and workflow automation, Nexus ensures your AI-driven development is efficient, trackable, and continuous.

Key Features

• Token Guardian: Prevent surprise costs with real-time tracking, budget alerts, and automatic routing to cost-effective models.
• Memory Store: Build a long-term brain for your projects. Store architectural decisions, coding patterns, and preferences that persist across sessions.
• Context Engine: Keep your context window lean and relevant using intelligent message pruning, tool output trimming, and semantic compaction.
• Session Bridge: Transfer work between sessions without losing progress. Link related sessions and generate detailed handoff documents.
• Agent Orchestra: Spawn and coordinate multiple specialized agents in parallel with shared budget pools and centralized status tracking.
• Workflow Engine: Execute complex, multi-phase tasks with confidence. Use git-backed checkpoints to rollback and resume work at any step.
• Skills Manager: Dynamically discover and activate specialized skill sets that specialize your AI's behavior for specific tasks.
• Analytics: Gain deep insights into your development habits with detailed reports on token usage, session frequency, and tool performance.

Installation

To install Nexus, clone the repository into your OpenCode plugins directory:

git clone https://github.com/opencode-ai/nexus.git D:\OpenCode\Nexus
cd D:\OpenCode\Nexus
npm install
npm run build

Then, enable the plugin in your .opencode/plugins.json configuration file.

Configuration

Nexus is configured via .opencode/nexus.config.json. Below are the available options:

{
  "tokenGuardian": {
    "daily": 100000,
    "session": 50000,
    "alert": 80
  },
  "memoryStore": {
    "enabled": true,
    "maxInjected": 5
  },
  "analytics": {
    "enabled": true,
    "retention": 90
  },
  "contextEngine": {
    "maxContextSize": 50,
    "maxToolOutputLength": 2000,
    "enableSemanticSearch": false
  },
  "agentOrchestra": {
    "maxConcurrentAgents": 5,
    "budgetPoolSize": 500000,
    "defaultBudgetPerAgent": 100000
  },
  "skillsManager": {
    "autoDiscover": true,
    "scanDirectories": ["./skills", "./.opencode/skills"]
  },
  "workflowEngine": {
    "checkpointBranch": "nexus-checkpoints"
  }
}

Configuration Reference

| Section | Option | Description | Default | |---------|--------|-------------|---------| | tokenGuardian | daily | Daily token budget limit. | 100,000 | | | session | Per-session token budget limit. | 50,000 | | | alert | Alert threshold percentage (0-100). | 80 | | memoryStore | enabled | Enable persistent memory injection. | true | | | maxInjected | Max memories to inject into system prompt. | 5 | | analytics | enabled | Enable metrics tracking. | true | | | retention | Days to retain analytics data. | 90 | | contextEngine | maxContextSize | Max messages to keep in active context. | 50 | | | maxToolOutputLength | Max length for tool outputs before trimming. | 2000 | | | enableSemanticSearch | Enable semantic search for relevance (future). | false | | agentOrchestra | maxConcurrentAgents | Max agents that can run in parallel. | 5 | | | budgetPoolSize | Total tokens available for all agents. | 500,000 | | | defaultBudgetPerAgent | Default budget allocated to new agents. | 100,000 | | skillsManager | autoDiscover | Automatically scan for skill files. | true | | | scanDirectories | Paths to search for .skill.yaml files. | ["./skills"] | | atlassian | cloudId | Jira/Confluence Cloud ID for integration. | - | | | baseUrl | Custom base URL for Atlassian services. | - | | smartSync | syncIntervalMinutes | Interval for background synchronization. | 30 | | | enableAutoSync | Enable automatic background syncing. | false | | workflowEngine | checkpointBranch | Branch name for git-backed checkpoints. | nexus-checkpoints |

Modules and Tools

1. Token Guardian

Tracks token usage and enforces budgets to control costs.

• nexus_token_status: Show current session and daily token usage with budget status.
• nexus_token_budget: View or modify token budget limits (daily, session, alert threshold).
• nexus_token_history: Show token usage history for the past N days.

Example: Check your current budget status:

nexus_token_status

2. Memory Store

Persistent storage for patterns, decisions, and project-specific knowledge.

• nexus_remember: Store a new memory (content, tags, expiresInDays).
• nexus_recall: Search memories by keyword or tags.
• nexus_forget: Delete a memory by ID.
• nexus_memories: List all stored memories in a table.

Example: Save an architectural decision:

nexus_remember --content "Use Postgres for all relational data" --tags architecture,database

3. Context Engine

Optimizes the context window for better performance and lower costs.

• nexus_context_status: Show context utilization and pruning stats.
• nexus_context_pin: Pin/unpin a message to protect it from pruning.
• nexus_context_strategy: Switch compaction strategy (smart, recency, relevance).

Example: Pin an important requirement:

nexus_context_pin --messageID "msg_12345" --action pin

4. Session Bridge

Connects separate sessions for a continuous development experience.

• nexus_handoff_create: Generate a handoff document for another session.
• nexus_handoff_resume: Load a handoff document into the current session.
• nexus_handoff_list: List available handoff documents.
• nexus_session_link: Manually link the current session to a parent or related session.

Example: Create a handoff before closing:

nexus_handoff_create --title "Refactoring Auth Module"

5. Agent Orchestra

Manages multi-agent workflows with centralized coordination.

• nexus_agent_spawn: Spawn a single agent with a specific budget and prompt.
• nexus_agent_coordinate: Execute multiple tasks in parallel using specialized agents.
• nexus_agent_status: Check runtime and token usage of spawned agents.
• nexus_budget_status: Check the status of the shared agent budget pool.

Example: Spawn an agent to research a library:

nexus_agent_spawn --agentType "explorer" --prompt "Find the best library for PDF generation in Node.js" --budget 50000

6. Workflow Engine

Automates complex multi-step processes with safety features.

• nexus_workflow_start: Start a workflow from a definition file (YAML/JSON).
• nexus_workflow_status: Get detailed progress of a running workflow.
• nexus_workflow_checkpoint: Create a manual git-backed checkpoint.
• nexus_workflow_rollback: Revert workspace state to a previous checkpoint.
• nexus_workflow_resume: Continue a paused or rolled-back workflow.
• nexus_workflow_list: List all active and completed workflows.

Example: Start a deployment workflow:

nexus_workflow_start --workflowPath "./workflows/deploy.yaml"

7. Skills Manager

Specializes the AI's behavior by loading domain-specific knowledge.

• nexus_skills_list: List all available skills in the workspace.
• nexus_skills_activate: Activate a skill by ID.
• nexus_skills_deactivate: Deactivate a skill by ID.
• nexus_skills_search: Search for skills by name or category.
• nexus_skills_info: View the detailed system prompt and metadata of a skill.

Example: Activate the React expert skill:

nexus_skills_activate --skillID "react-master"

8. Analytics

Provides transparency into your development metrics.

• nexus_analytics_summary: High-level overview of messages, tokens, and tools.
• nexus_analytics_sessions: Breakdown of session activity and errors.
• nexus_analytics_tokens: Detailed usage by model and token type.
• nexus_analytics_tools: Ranking of most frequently used tools.
• nexus_analytics_export: Export metrics in JSON or CSV format.

Skills System

Nexus uses a dynamic skills system that allows you to define specialized behaviors in .skill.yaml or .skill.json files.

Skill File Structure

id: "typescript-expert"
name: "TypeScript Expert"
description: "Advanced TypeScript patterns and type-safety guidance"
category: "programming"
systemPrompt: |
  You are a TypeScript master. Always prefer strict types and avoid 'any'.
  Use utility types like Pick, Omit, and Partial where appropriate.
metadata:
  version: "1.0.0"
  author: "Nexus Team"

Skills are automatically discovered in your workspace and can be activated using nexus_skills_activate. Once active, their systemPrompt is automatically injected into every interaction.

Deployment

To deploy Nexus in a production environment:

1. Ensure all dependencies are installed: npm install --production
2. Build the project: npm run build
3. Copy the dist directory and package.json to your plugin host.
4. Ensure the .nexus storage directory has write permissions.

Troubleshooting

• Budget Exceeded: If you hit a token limit, use nexus_token_budget to increase your daily or session limits.
• Skill Not Found: Ensure your .skill.yaml files are in a directory listed in the skillsManager.scanDirectories config.
• Workflow Rollback Failed: Ensure you have a git repository initialized in your workspace, as the Workflow Engine uses git for checkpoints.
• Storage Issues: Nexus stores data in a .nexus directory in your workspace. Ensure this directory is not ignored by your environment.

License

This project is licensed under the ISC License.