OctoFinance

Imported from satomic/OctoFinance (AGENTS.md). Install upstream with npx skills add satomic/OctoFinance. Copyright stays with the author.

AGENTS.md — OctoFinance AI Agent Instructions

Agent Identity

Name: OctoFinance AI FinOps Assistant Platform: GitHub Copilot Python SDK (github-copilot-sdk) Runtime: Copilot CLI (JSON-RPC control via SDK)

The OctoFinance AI agent is a specialized FinOps assistant that helps GitHub Copilot administrators optimize costs, manage seats, and gain insights across multiple organizations and enterprises.

System Prompt

The agent operates under the following system prompt (defined in backend/app/services/copilot_engine.py):

You are OctoFinance AI FinOps Assistant, specialized in helping GitHub Copilot
administrators optimize costs and manage seats efficiently.

Your responsibilities:
1. Proactively analyze Copilot usage data to identify waste and inefficiency
2. Provide specific cost optimization recommendations with estimated savings amounts
3. Execute operational actions (remove/add seats) after admin confirmation
4. Compare across organizations, teams, and users
5. Generate FinOps reports and insights

Key behaviors:
- Always use the provided tools to get real data before making recommendations
- Include specific numbers: cost, savings, user counts, dates
- When recommending seat removal, use record_recommendation to create actionable items
- Respond in the same language as the user's message
- Be proactive: if asked about usage, also mention cost implications
- For destructive operations (seat removal), always explain the impact first
  and ask for confirmation

Available data dimensions:
- Seats: who has Copilot, when they last used it, which team they belong to
- Usage Reports: org-level and user-level usage metrics (28-day or specific day),
  feature adoption, engagement data
- Billing: plan type, cost per seat, total cost, waste
- Metrics: detailed IDE completions, chat usage, PR summaries (legacy API)
- AI Credits: per-model breakdown of AI credit consumption,
  pricing, and costs (UBB - Usage-Based Billing)

Copilot AI credits (UBB, effective June 1, 2026):
Each Copilot plan includes a monthly allowance of AI credits per user; Copilot
Enterprise includes a larger allowance than Copilot Business. Usage beyond the
included allowance is billed per the model's price per credit (e.g. ~$0.01/credit).

For usage data, prefer the new usage report tools (get_usage_report,
get_users_usage_report) which use the latest Copilot Usage Metrics API.
You can also use fetch_org_usage_report / fetch_org_users_usage_report to get
live data directly from GitHub API for a specific day or the latest 28-day period.

Tool Catalog (43 Tools)

Seat Management Tools (backend/app/tools/seat_tools.py)

Usage Analysis Tools (backend/app/tools/usage_tools.py)

Billing & ROI Tools (backend/app/tools/billing_tools.py)

Action & Recommendation Tools (backend/app/tools/action_tools.py)

Cost Center Tools (backend/app/tools/cost_center_tools.py)

Budget Tools — UBB (backend/app/tools/budget_tools.py)

Budget writes require the PAT to carry the manage_billing:copilot scope.

Enterprise Team Tools (backend/app/tools/enterprise_team_tools.py)

Enterprise team endpoints only accept classic PATs: read:enterprise for reads, admin:enterprise for writes. Fine-grained and GitHub App tokens are rejected.

No Copilot dataset carries an enterprise-team field. Team attribution is resolved by joining the synced roster (data/enterprise_teams/{slug}_latest.json) against seats/usage/AI-credit data on the user login. Teams may contain unaffiliated users who belong to no organization and therefore never appear in org seat data.

Data Flow Architecture

Read Path (Cached Data)

User Question
  → Copilot SDK Session (LLM selects tools)
    → Tool reads from DataCollector
      → DataCollector loads JSON from data/{type}/{org}.json
        → Tool returns structured data to LLM
          → LLM generates analysis response

Read Path (Live API)

User Question
  → Copilot SDK Session (LLM selects fetch_* tool)
    → Tool calls GitHubAPI via APIManager
      → GitHubAPI makes HTTP request to GitHub REST API
        → Response cached locally + returned to LLM
          → LLM generates analysis response

Write Path (Operations)

User requests action
  → LLM calls record_recommendation
    → Recommendation stored in data/recommendations.json
      → Shown in frontend Action Panel
        → Admin clicks "Approve"
          → Backend calls GitHub API (remove seat / add team member)
            → Result logged in data/audit_log.json

Session Management

Session Isolation

Each chat session gets its own working directory at data/sessions/{session_id}/. The Copilot SDK uses this directory for:

• Session state persistence (.copilot_session_id)
• Session-specific data cache
• Copilot Skills (.github/skills/)

Session Lifecycle

1. Create: CopilotClient.create_session(config) — registers tools, system prompt, working directory
2. Resume: CopilotClient.resume_session(sdk_session_id, config) — restores state after backend restart
3. Send: session.send({"prompt": message}) — triggers agentic loop with event streaming
4. Destroy: session.destroy() — cleanup

Copilot Skills

The SDK discovers skills from .github/skills/ within the session working directory. Skills are markdown-defined capabilities that extend the agent's knowledge base without code changes.

How to Extend the Agent

Adding a New Tool

1. Define the tool in backend/app/tools/:

from pydantic import BaseModel, Field
from copilot import define_tool

class MyToolParams(BaseModel):
    org: str = Field(default="", description="Organization name")

@define_tool(description="Clear description of what this tool does")
def my_new_tool(params: MyToolParams) -> str:
    # Read from collector or call API
    result = collector.load_latest("data_type", params.org)
    return json.dumps(result)

2. Register in copilot_engine.py:

from ..tools.my_tools import create_my_tools

def _build_tools_for_session(self, working_directory):
    tools = (
        create_seat_tools(...)
        + create_usage_tools(...)
        + create_billing_tools(...)
        + create_action_tools(...)
        + create_my_tools(...)  # Add here
    )
    return tools

Design Principles

Configuration

Environment

• Python 3.13+ with FastAPI
• GitHub Copilot CLI must be installed and authenticated
• GitHub PATs configured via the web UI (stored in data/pats.json)

Key Files