IncludeCPP 3.3.4

Professional C++ Python bindings with type-generic templates, pystubs and native threading

IncludeCPP

Write C++ code, use it in Python. Auto-generates pybind11 bindings.

pip install IncludeCPP

First Steps

Project Setup

includecpp init

Creates:

• cpp.proj - project configuration
• include/ - your C++ source files
• plugins/ - generated binding definitions

Write C++ Code

Put your code in namespace includecpp:

// include/fast_list.cpp
#include <vector>

namespace includecpp {

class FastList {
public:
    void append(int val) { data.push_back(val); }
    int get(int i) { return data[i]; }
private:
    std::vector<int> data;
};

int add(int a, int b) { return a + b; }

}  // namespace includecpp

The parser only scans code inside namespace includecpp. Everything else is ignored.

Generate Bindings

includecpp plugin fast_list include/fast_list.cpp

This runs a C++ parser that:

1. Scans your source files for classes, methods, functions
2. Extracts signatures, return types, parameter names
3. Generates plugins/fast_list.cp with binding instructions

Build

includecpp rebuild

Compiles your C++ into a Python extension module (.pyd on Windows, .so on Linux/Mac).

Use in Python

from includecpp import fast_list

my_list = fast_list.FastList()
my_list.append(42)
print(fast_list.add(1, 2))  # 3

Alternative syntax:

from includecpp import CppApi

api = CppApi()
fast_list = api.include("fast_list")

How to Start

Minimal Example

# 1. Create project
mkdir myproject && cd myproject
includecpp init

# 2. Write C++ (include/math.cpp)
cat > include/math.cpp << 'EOF'
namespace includecpp {
    int square(int x) { return x * x; }
}
EOF

# 3. Generate plugin
includecpp plugin math include/math.cpp

# 4. Build
includecpp rebuild

# 5. Use
python -c "from includecpp import math; print(math.square(7))"

Development Workflow

For active development, use auto:

includecpp auto math

This regenerates the .cp file from source and rebuilds in one command.

For fastest iteration:

includecpp rebuild --fast

Skips unchanged files. ~0.4s when nothing changed.

How IncludeCPP Works

Architecture

Your C++ Source            Plugin File (.cp)           Python Module
include/math.cpp    --->   plugins/math.cp     --->    math.cpXXX.pyd
     ^                           ^                          ^
     |                           |                          |
  C++ parser              Binding config             pybind11 compiled
  extracts API            (editable)                 extension

The Parser

The C++ parser (parser.cpp) runs as a compiled executable. It:

1. Tokenizes your C++ source files
2. Identifies the namespace includecpp block
3. Extracts:
   • Class names and inheritance
   • Method signatures (name, return type, parameters)
   • Function signatures
   • Template instantiations
   • Const/static qualifiers
4. Outputs structured binding instructions to .cp files

Plugin Files (.cp)

The .cp format is a declarative binding specification:

SOURCE(math.cpp) math

PUBLIC(
    math CLASS(Calculator) {
        CONSTRUCTOR()
        CONSTRUCTOR(int)
        METHOD(add)
        METHOD_CONST(getValue)
        FIELD(value)
    }

    math FUNC(square)
    math TEMPLATE_FUNC(maximum) TYPES(int, float, double)
)

Key directives:

• SOURCE(file.cpp) module_name - links source to module
• PUBLIC(...) - defines public bindings
• CLASS(Name) - expose a class
• STRUCT(Name) - expose a struct
• FUNC(name) - expose a free function
• METHOD(name) - expose a class method
• METHOD_CONST(name, signature) - for overloaded methods
• TEMPLATE_FUNC(name) TYPES(...) - instantiate template
• CONSTRUCTOR(args) - expose constructor
• FIELD(name) - expose member variable
• DEPENDS(mod1, mod2) - declare module dependencies

Build System

The build manager:

1. Reads cpp.proj configuration
2. Parses all .cp files in plugins/
3. Generates pybind11 binding code
4. Compiles using CMake with detected compiler (MSVC, GCC, Clang)
5. Places output in ~/.includecpp/builds/ (not in your project)
6. Creates a registry so Python can find modules

Caching layers:

• Object files: Only recompile changed .cpp files
• Generator cache: Compiler/CMake detection runs once
• SHA256 hashes: Skip unchanged modules entirely

CLI Reference

Use includecpp <command> --help for details.

Command	Description
init	Create project structure
plugin <name> <files>	Generate .cp from C++ sources
auto <plugin>	Regenerate .cp and rebuild
auto --all	Regenerate and rebuild all plugins
auto --all -x <name>	All plugins except specified
fix <module>	Analyze C++ code for issues
fix --all	Analyze all modules
fix --undo	Revert last fix changes
fix --ai <module>	AI-enhanced code analysis
ai key <key>	Set OpenAI API key
ai enable	Enable AI features
ai disable	Disable AI features
ai model --list	List available models
ai model set <name>	Set active model
ai --info	Show AI configuration and usage
ai optimize <module>	AI code optimization
ai optimize --agent "<task>"	Custom AI task
ai ask "<question>"	Ask about project with full context
ai ask "<question>" <module>	Ask about specific module
ai edit "<task>"	Edit code with AI assistance
ai edit "<task>" --think2	Thorough edit mode
ai undo	Restore files after AI changes
rebuild / build	Compile all modules
get <module>	Show module API (classes, methods, functions)
install <name>	Install community module
update	Update IncludeCPP
bug	Report an issue
--doc	Show documentation
--changelog	Show latest version changelog
cppy convert <files> --cpp	Convert Python to C++
cppy convert <files> --py	Convert C++ to Python
cppy convert <files> --cpp --no-h	Convert without header
cppy convert <files> --cpp --ai	AI-assisted conversion
cppy analyze <files>	Analyze code structure
cppy types	Show type mapping tables

Build Flags

includecpp rebuild                  # Standard build
includecpp rebuild --clean          # Full rebuild, clear caches
includecpp rebuild --fast           # Fast incremental (~0.4s if unchanged)
includecpp rebuild --verbose        # Show compiler output
includecpp rebuild -m crypto        # Build specific module only
includecpp rebuild -j 8             # Use 8 parallel jobs
includecpp rebuild --keep           # Keep generator between builds
includecpp rebuild --no-incremental # Force full recompilation
includecpp rebuild --this           # Build current directory as module

Fast Mode

--fast enables object file caching:

Scenario	Time
No changes	~0.4s
Source changed	~5-10s
Full rebuild	~30s

Clear caches with --clean.

Incompatible Flag Combinations

Flags	Reason
--fast + --no-incremental	Fast mode requires incremental
--fast + --clean	Fast uses caches, clean deletes them
--fast + --this	Not supported together
--incremental + --no-incremental	Contradictory

Advanced Features

AI Integration

IncludeCPP integrates with OpenAI for intelligent code analysis and optimization.

Setup

includecpp ai key sk-your-api-key-here
includecpp ai enable

Available Models

includecpp ai model --list

• gpt-5 (default) - 256k context
• gpt-5-nano - 32k context, fast
• gpt-4o - 128k context
• gpt-4-turbo - 128k context
• gpt-3.5-turbo - 16k context

AI-Enhanced Fix

includecpp fix --ai mymodule
includecpp fix --ai --all

Sends source files to AI for analysis, suggests improvements while preserving all existing functions.

AI Optimize

includecpp ai optimize mymodule                        # Optimize module sources
includecpp ai optimize --file src/utils.cpp            # Optimize specific files
includecpp ai optimize --agent mymodule "add SIMD"     # Custom task

AI Ask

Ask questions about your project with full context awareness:

includecpp ai ask "where is collision detection?"              # Search all modules
includecpp ai ask "how does chunk generation work?" chunk_utils  # Specific module
includecpp ai ask "explain the biome system" --file include/biomes.cpp
includecpp ai ask "list all public methods" --all -x tests      # All except tests

Supports: module name, --file, --all, -x/--exclude

AI Edit

Edit code with AI assistance:

includecpp ai edit "add logging to all methods" collision
includecpp ai edit "optimize the loop" --file include/utils.cpp
includecpp ai edit "add error handling" --all --think2          # Thorough mode

Flags:

• --file - specific files
• --all - all modules
• -x/--exclude - exclude modules
• --think2 - thorough analysis (more tokens)

AI Generate (Super Assistant)

The most powerful AI command - a full assistant with file operations and command execution.

# Basic usage
includecpp ai generate "add error handling to all functions" --file mymodule.cp

# Create new module from scratch
includecpp ai generate "fast SIMD math library" --t-new-module simd_math

# Planning mode (search, analyze, then execute)
includecpp ai generate "refactor for better performance" --t-plan --think2

# With Python file (auto-detect module usage)
includecpp ai generate "update api methods" --file mymod.cp --python main.py

# Full context mode
includecpp ai generate "comprehensive optimization" --t-max-context --think3

Flags:

Flag	Description
--file <path>	Add files (multiple allowed). .cp files auto-resolve to source
--think/2/3	Extended context and planning
--websearch	Enable web research
--t-max-context	No context reduction
--t-plan	Search/grep before executing
--t-new-module <name>	Create new module (cpp + plugin + build)
--python <file.py>	Include Python file, auto-detect modules
--confirm	Skip confirmations

AI Tools

List available tools for the generate command:

includecpp ai tools

Available tools: READ_FILE, WRITE_FILE, EDIT_FILE, DELETE_FILE, CREATE_FOLDER, LIST_FOLDER, SEARCH_FILES, GREP, RUN_CMD, INCLUDECPP_CMD

Build Error Analysis

When AI is enabled and rebuild fails, the build error is automatically analyzed:

• Root cause identification
• Code fix suggestions
• Prevention tips

Configuration

includecpp ai --info          # Show status, model, usage stats
includecpp ai disable         # Disable without removing key

API key stored in ~/.includecpp/.secret.

Overloaded Methods

Specify the signature to disambiguate:

MODULE CLASS(Circle) {
    METHOD_CONST(intersects, const Circle&)
    METHOD_CONST(intersects, const Rect&)
}

Template Instantiation

MODULE TEMPLATE_FUNC(maximum) TYPES(int, float, double)

MODULE STRUCT(Point) TYPES(int, float) {
    FIELD(x)
    FIELD(y)
}

Generates maximum_int, maximum_float, maximum_double and Point_int, Point_float.

Module Dependencies

DEPENDS(math_utils, geometry)

Ensures dependent modules build first.

VSCode IntelliSense

Generates .pyi stub files for autocomplete. Enable in cpp.proj:

{
  "CPI-IntelliSense": true
}

CPPY Code Conversion

Convert code between Python and C++ with full support for classes, functions, and type hints.

Python to C++

includecpp cppy convert math_utils.py --cpp
includecpp cppy convert data.py --cpp --no-h  # Skip header
includecpp cppy convert src/*.py --cpp -o include/

Converts Python code to optimized C++ with:

• Type hints mapped to C++ types (int, str -> std::string, List -> std::vector)
• Classes with constructors, methods, fields
• Functions with proper signatures
• List comprehensions to STL algorithms
• Exception handling to try/catch

C++ to Python

includecpp cppy convert utils.cpp --py
includecpp cppy convert mymodule.cp --py  # Auto-resolve SOURCE()

Converts C++ to Python with:

• STL types mapped to Python equivalents
• Classes with type hints
• Methods become class methods with self
• Structs become dataclasses

AI-Assisted Conversion

includecpp cppy convert complex_lib.py --cpp --ai
includecpp cppy convert advanced.cpp --py --ai -v

The --ai flag enables intelligent conversion with:

• Section-by-section analysis and processing
• Automatic --think2 context level
• Comprehensive rulebase for precise conversions
• pybind11 wrappers for Python features without C++ equivalents:
  • Generators -> callback pattern / py::iterator
  • Async/await -> std::async / std::future
  • Context managers -> RAII pattern
  • Duck typing -> templates with concepts
• Reports API changes to user
• Fallback to standard conversion if AI unavailable

Workaround Examples:

Python Feature	C++ Workaround
yield	Callback pattern or py::iterator
async/await	std::async + std::future
with context	RAII ScopedResource class
List comprehension	transform_to_vector template
Dict comprehension	transform_to_map template
Dynamic attributes	py::object

Analyze Code

includecpp cppy analyze math.py           # View structure
includecpp cppy analyze utils.cpp --json  # JSON output

Type Mapping

includecpp cppy types  # Show conversion tables

Python	C++
int	int
float	double
str	std::string
bool	bool
List[T]	std::vector
Dict[K,V]	std::unordered_map<K,V>
Optional[T]	std::optional
Tuple[...]	std::tuple<...>

Configuration

cpp.proj

{
  "project": "MyProject",
  "include": "/include",
  "plugins": "/plugins",
  "compiler": {
    "standard": "c++17",
    "optimization": "O3"
  }
}

Options:

• project - project name
• include - C++ source directory
• plugins - plugin file directory
• compiler.standard - C++ standard (c++11, c++14, c++17, c++20)
• compiler.optimization - optimization level (O0, O1, O2, O3)

Requirements

• Python 3.8+
• C++ compiler (g++, clang++, MSVC)
• pybind11 (installed automatically)
• CMake (for build generation)

Changelog

v3.3.4

• New --ai flag for cppy convert - AI-assisted code conversion
• Automatic --think2 context for intelligent conversion
• Comprehensive rulebase for Python <-> C++ translations
• pybind11 wrappers for unconvertible Python features:
  • Generators -> callback pattern / py::iterator
  • Async/await -> std::async / std::future
  • Context managers -> RAII pattern
  • List/dict comprehensions -> helper templates
• API change detection and user notification
• Section-by-section analysis and conversion
• Graceful fallback to standard conversion if AI unavailable

v3.3.3

• Fixed ai generate loop bug creating duplicate file changes
• Fixed unused variable warning in cppy_converter.py
• Improved deduplication of file changes in AI generate

v3.3.2

• Fixed version display bug in includecpp update --version
• New cppy convert command for Python <-> C++ code conversion
• Convert Python to optimized C++ with --cpp flag
• Convert C++ to Python with --py flag
• --no-h flag to skip header generation
• cppy analyze command to inspect code structure
• cppy types command to view type mapping tables
• Full support for classes, structs, functions, templates

v3.3.1

• Fixed ai generate --t-new-module not creating files (tool parser bug)
• Fixed ai generate --t-plan not executing after planning (now runs automatically)
• Added JSON-style tool call parsing as fallback
• Improved prompts with explicit format instructions

v3.3.0

• New ai generate "<task>" - Super assistant with tool execution
• New ai tools - List available AI tools
• Tools: READ_FILE, WRITE_FILE, EDIT_FILE, DELETE_FILE, CREATE_FOLDER, LIST_FOLDER, SEARCH_FILES, GREP, RUN_CMD, INCLUDECPP_CMD
• --t-max-context - Full context mode
• --t-plan - Planning mode with search/grep before executing
• --t-new-module <name> - Create new module from scratch (cpp + plugin + build)
• --python <file.py> - Include Python files, auto-detect module usage
• Improved ai edit parser for complex tasks (better fallback detection)
• Fixed "No changes needed" false positives in ai edit

v3.2.5

• Fixed timeout issue for ai ask and ai edit with --think2/--think3 flags
• --think3 now has no timeout limit for complex operations
• --think2 timeout increased to 7 minutes
• AI can now ask clarifying questions during --think2/--think3 operations

v3.2.4

• Fixed UTF-16/BOM encoding error in plugin command (source file reading)

v3.2.3

• Fixed FIELD() syntax: now outputs FIELD(name) not FIELD(type, name)
• Fixed documentation: PUBLIC() not PUBLIC:
• Fixed AI context to match actual .cp syntax

v3.2.2

• Plugin command now detects comma-separated field declarations (e.g., double x, y, z; generates 3 FIELD entries)
• Fixed ai optimize timeout for multi-file operations (increased to 5 minutes)
• AI ask now extracts relevant CLI implementation when asking about commands/flags

v3.2.1

• Fixed encoding error in ai ask output on Windows (GPT Unicode characters like non-breaking hyphen)

v3.2.0

• AI context limits: 3K (standard), 5K (--think), 10K (--think2), 25K (--think3) lines
• AI now has full IncludeCPP knowledge (namespace requirements, .cp format, common errors)
• New --think flag for short planning mode (5K context)
• New --websearch flag for web research (requires Brave API)
• Daily token limit: 220K default, auto-resets at midnight
• New commands: ai limit, ai limit set <N>, ai limit get
• Fixed "No changes needed" issue in ai edit (now more assertive)
• Improved fix --ai error detection with line numbers and error categorization
• Settings GUI now shows daily limit option
• Build info from AppData included in AI context

v3.1.10

• Fixed diff view encoding on Windows (replaced Unicode box chars with ASCII)

v3.1.9

• AI commands now show colored diff before confirmation prompts
• Renamed --auto to --confirm for AI confirmation skipping (fix --confirm, ai edit --confirm, ai optimize --confirm)
• Fixed Windows encoding errors ('charmap' codec issue)
• All file operations now use UTF-8 encoding explicitly

v3.1.8

• --think2 and --think3 flags added to ai ask and ai edit commands
• Extended context and web research support for all AI commands
• Fixed ai undo command error

v3.1.7

• --auto-ai flag for rebuild, build, and auto commands
• Auto-fix build errors with AI and retry automatically (max 3 attempts)
• AI has CLI access (can run includecpp plugin <module> for .cp regeneration)
• --think2 for extended context (500 lines per file, careful analysis)
• --think3 for max context + web research + planning mode (requires Brave API)
• includecpp ai token --brave <TOKEN> for Brave Search API
• includecpp settings opens PyQt6 settings panel (pip install PyQt6)
• Changes from --auto-ai can be reverted with includecpp ai undo

---

MIT License | v3.3.4 | GitHub