sutrakit 0.1.8

A comprehensive AI-powered code analysis and automation CLI tool

Sutra Knowledge CLI

An intelligent codebase analysis and knowledge management tool that provides AI-powered insights, semantic search capabilities, and comprehensive project understanding through advanced parsing and embedding technologies. Focus on writing your code and thinking of the business-logic! The CLI will take care of the rest.

⚡️ Quick Start

First, download and install Python. Version 3.8 or higher is required.

Installation is done by using the pip install command:

pip install sutrakit

Setup environment

Sets up ~/.sutra directory, downloads ML models, creates config files, sets environment variables, and prepares BAML client for AI code analysis.

sutrakit-setup

That's all you need to know to start! 🎉

Indexing Your Projects

To enable analysis, each project must be indexed. This process parses the codebase, extracts structures, and builds embeddings for semantic search.

1. Navigate to your project directory (e.g., cd my-project).
2. Run sutrakit – if the project isn't indexed, you'll be prompted to do so.
   • Confirm indexing when asked; it typically takes a few minutes depending on project size.

For ecosystems with multiple related projects (e.g., backend, frontend, microservices):

• Repeat the above in each project's directory.
• Sutrakit automatically links them by matching connections, creating a dependency graph for ecosystem-wide analysis.

Important Note:

• For the Roadmap Agent to fully discover and navigate inter-project connections (e.g., API calls, message queues, WebSockets), cross-indexing is required during the indexing phase. This builds a dependency graph of external links that standard parsing might miss. Without it, the agent can't trace code flows across projects, resulting in incomplete roadmaps.
• Do not run cross-indexing parallelly for multiple projects, as it can lead to conflicts and incomplete or incorrect dependency graphs.

📝 Key Features

Sutrakit is an orchestrator for AI agents and services, focused on multi-project codebase analysis and management. It helps developers handle complex ecosystems by providing intelligent insights and automated workflows. Below are the core features, with a diagram for the key component.

• AI-Powered Roadmap Agent:

  • Processes user queries to create minimal plans across projects.
  • Identifies change locations, reuses code, and defines integrations.
  • Refines via feedback; orchestrates sub-agents for execution.

• Orchestration of Sub-Agents:

  • Spawns AI sub-agents for parallel project updates.
  • Handles dependencies seamlessly.

• Cross-Indexing Service:

  • Discovers and indexes external connections (e.g., APIs, message queues, WebSockets) beyond standard parsing, using advanced matching for identifiers, parameters, wrappers, and variables.
  • Builds a dependency graph by scanning new projects against existing ones, creating links for matched connections to enable seamless navigation and hopping between projects during analysis.

• Semantic Search and Code Analysis:

  • Queries codebases with semantic/keyword tools.
  • Manages memory to optimize operations.

Roadmap Agent Workflow

flowchart TD
    A[User Query] --> D[Analyze & Plan]
    D --> E[Verify & Review]
    E -->|Refine| D
    E -->|Approve| F[Execute via Sub-Agents]
    F --> SA[Sub-Agent: Project A]
    F --> SB[Sub-Agent: Project B]
    F --> SC[Sub-Agent: Project C]

Use Cases

Sutrakit excels in interconnected projects like microservices or full-stack apps:

• New Feature: Maps backend-to-frontend changes; generates contracts; updates via sub-agents.
• Bug Fix: Traces dependencies; plans minimal fixes.
• Refactor: Analyzes patterns; roadmaps reusable updates.
• Onboard Repo: Indexes and links to ecosystem for integrations.

This keeps focus on practical value to see if it fits your needs.

Configuration

Sutrakit allows customization through the system configuration file located at ~/.sutra/config/system.config. This JSON file controls various aspects of the tool, such as database paths, storage directories, embedding models, logging, and LLM providers. You can edit it manually to tweak settings—changes take effect on the next run. Always back up the file before modifying, and ensure valid JSON format to avoid errors.

Here's a partial view of the config file (focusing on the LLM section for brevity; other sections like database and storage are omitted):

{
  ...
  "llm": {
    "provider": "aws",
    "llama_model_id": "meta/llama-3.1-8b-instruct",
    "claude_model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
    "gemini_model": "gemini-1.5-flash",
    "aws": {
      "access_key_id": "YOUR_ACCESS_KEY",
      "secret_access_key": "YOUR_SECRET_KEY",
      "region": "us-east-2",
      "model_id": "us.anthropic.claude-sonnet-4-20250514-v1:0"
    },
    "anthropic": {
      "api_key": "YOUR_API_KEY",
      "model_id": "us.anthropic.claude-sonnet-4-20250514-v1:0"
    },
    "gcp": {
      "api_key": "YOUR_API_KEY",
      "project_id": "YOUR_PROJECT_ID",
      "location": "us-central1",
      "llm_endpoint": "https://us-central1-aiplatform.googleapis.com/v1/projects/{project_id}/locations/us-central1/endpoints/openapi/chat/completions"
    },
  }
  ...
}

Example: Changing the LLM Provider

The "llm" section lets you switch AI providers (e.g., for the Roadmap Agent) and configure credentials. By default, it's set to "aws". To change it:

1. Update "provider" to one of: "aws", "anthropic", "gcp", or "superllm".
2. Fill in the corresponding subsection with your API keys or credentials (leave others blank if unused).
3. Optionally, adjust model IDs for specific LLMs.

Switch to Anthropic Example:

"llm": {
  "provider": "anthropic",
  "llama_model_id": "meta/llama-3.1-8b-instruct",
  "claude_model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
  "gemini_model": "gemini-1.5-flash",
  "aws": { /* Leave as-is or blank */ },
  "anthropic": {
    "api_key": "sk-ant-your-anthropic-api-key-here",
    "model_id": "claude-3-5-sonnet-20240620"
  },
  "gcp": { /* Leave as-is or blank */ },
  "superllm": { /* Leave as-is or blank */ }
}

After saving, restart Sutrakit to apply changes. For other sections (e.g., logging level or embedding model), edit values directly—refer to the file for details.

⭐️ Project assistance

If you want to say thank you or/and support active development of Sutra Knowledge CLI:

• Add a GitHub Star to the project.
• Write interesting articles about project on Dev.to, or personal blog.

🏆 A win-win cooperation

And now, I invite you to participate in this project! Let's work together to create the most useful tool for developers on the web today.

• Issues: ask questions and submit your features.
• Pull requests: send your improvements to the current.

Together, we can make this project better every day! 😘