PrimeAgent Main File: Why There's No main.py and What Actually Runs the Agent

PrimeAgent does not use a main.py file; instead, the shell script prime-agent.sh serves as the primary entry point that launches the TypeScript-based runtime and terminal UI.

The PrimeIntelllect-ai/prime-agent repository follows a Node.js-first architecture where the canonical "main" role is fulfilled by a bash launcher rather than Python. Understanding this entry-point structure is essential for contributors and users who expect a traditional Python if __name__ == "__main__" pattern.

The Actual Entry Point: prime-agent.sh

The file prime-agent.sh at the repository root is the sole entry point for running PrimeAgent. It performs three critical initialization steps before handing control to the compiled runtime.

Environment Preparation

The script ensures that supporting Python tools are available by activating a local virtual environment:

#!/usr/bin/env bash
set -e

# Activate Python virtualenv for auxiliary scripts

source .venv/bin/activate 2>/dev/null || python3 -m venv .venv

Runtime Launch

After environment setup, prime-agent.sh invokes the Node.js bundle that contains the compiled TypeScript:

# Export runtime configuration

export NODE_OPTIONS="--max-old-space-size=4096"

# Launch the PrimeAgent daemon and TUI

node ./dist/prime-agent.js "$@"

This delegation pattern keeps the shell layer thin—environment setup only—while the heavy logic resides in the packages/ directory.

What the Compiled Entry Point Executes

The dist/prime-agent.js file generated from TypeScript sources in packages/ai/ and packages/tui/ performs the actual application bootstrap:

• Daemon initialization – Loads configuration from config/prime-agent.yaml
• Plugin system startup – Registers agent capabilities from packages/ai/src/plugins/
• TUI attachment – Opens the interactive interface defined in packages/tui/src/index.ts

No Python def main() or __main__ block exists anywhere in the codebase.

Auxiliary Python Scripts (Not Entry Points)

Several .py files appear in the repository but serve development utilities rather than runtime purposes:

File	Actual Role
scripts/render-logo.py	Generates ASCII splash screen for the TUI
scripts/benchmark.py	Performance testing harness for model inference
scripts/setup-dev.py	One-time developer environment configuration

These are invoked manually or by CI pipelines, never by prime-agent.sh during normal execution.

How to Run PrimeAgent Correctly

Given the absence of main.py, use these commands:

Standard launch (daemon + TUI):

./prime-agent.sh

Daemon-only mode (headless server):

./prime-agent.sh --daemon-only

Development mode (bypass compiled bundle):

npm run dev  # Direct TypeScript execution via ts-node

Summary

• No main.py exists in PrimeAgent; the repository uses Node.js/TypeScript as its primary runtime
• prime-agent.sh is the canonical entry point that prepares environment variables and launches dist/prime-agent.js
• TypeScript packages (packages/ai/, packages/tui/) contain the actual application logic compiled to JavaScript
• Python utilities in scripts/ are auxiliary tools, not part of the execution flow

Frequently Asked Questions

Why doesn't PrimeAgent use a Python main file?

PrimeAgent is architected as a TypeScript-first project to leverage Node.js's event-loop concurrency for real-time TUI updates and streaming LLM responses. Python is reserved for data-science utilities and benchmark scripts, not the core runtime.

Can I run PrimeAgent without the shell script?

Yes. If you have Node.js installed, execute node ./dist/prime-agent.js directly after building the project with npm run build. However, you may need to manually export environment variables that prime-agent.sh normally sets.

Where is the closest equivalent to if __name__ == "__main__"?

In packages/tui/src/index.ts, the bootstrap() function serves an analogous role—it's the first called function after the Node.js process starts and handles argument parsing before initializing the agent loop.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}