Skip to main content

Create State Python SDK

Version 0.6.0 | Built 2026-10-14 | createstate.ai

Give your AI coding assistant a persistent memory.

Create State transforms AI coding assistants from forgetful tools into persistent companions. Every insight, decision, and code pattern is captured in a knowledge graph that grows smarter with every interaction.

+------------------+     +------------------+     +------------------+
|   Day 1          |     |   Week 1         |     |   Week 2+        |
|   AI knows       | --> |   AI remembers   | --> |   AI understands |
|   nothing        |     |   your decisions |     |   your codebase  |
+------------------+     +------------------+     +------------------+

The Problem: Every time you start a new chat with your AI assistant, it forgets everything. Your architecture decisions, the bugs you've fixed, why you chose that framework - all gone.

The Solution: Create State captures knowledge continuously and restores it instantly. Your AI assistant picks up exactly where you left off, with full context of your project's history.

Requirements

Why Create State?

  • Persistent Memory - Decisions, code patterns, and insights survive across sessions
  • Knowledge Graph - Captures relationships between concepts in your codebase
  • Session Handoff - Save AI "thinking state" and restore it later
  • Autonomous Insights - Background analysis surfaces improvements you didn't ask for
  • Works Everywhere - Cursor, Claude Desktop, VS Code, or this SDK

Installation

pip install createstate

Or download directly from createstate.ai/web/sdk

Upgrading

To upgrade to the latest version:

# If installed via pip
pip install --upgrade createstate

# If installed from archive
cd createstate-X.Y.Z
pip install --upgrade .

Note: Your configuration (~/.createstate/config.json) is preserved during upgrades - you won't need to run create-state configure again.

Verify your version:

create-state --version

Quick Start

# Configure your API key (get one at createstate.ai/web/api-keys)
create-state configure

# Initialize a world model for your project (automatically set as active)
create-state init --name "My Project"

# Or import directly from GitHub (NEW in v0.3.0!)

# Connect GitHub first (if importing a private repository)
create-state auth github

# Import repository and create world model
create-state init --from-github https://github.com/owner/repo

# Check status of your active model
create-state status

# Status with specific display mode (taste_topology, semantic_graph, conceptual_identity, integrated)
create-state status --rendering-mode taste_topology

# Capture your codebase to the knowledge graph
create-state capture code ./src

# Ask questions about your project
create-state ask "why did we choose this architecture?"

# List all your world models
create-state models

# Switch to a different model (by name or ID)
create-state use "World Model from CLI"
# Or by ID (full or partial)
create-state use d8e850c0

The Knowledge Lifecycle

Create State follows a simple lifecycle that builds institutional memory over time:

    +==========================================+
    |          THE KNOWLEDGE LIFECYCLE         |
    +==========================================+

    1. CREATE          2. CAPTURE           3. SYNTHESIZE
       World Model        Code & Context       Knowledge

         [New]              [+++]               [=]
          |                  |||                 |
          v                  vvv                 v
    +----------+       +----------+        +----------+
    | Empty    |  -->  | Growing  |  -->   | Rich     |
    | Graph    |       | Graph    |        | Summary  |
    +----------+       +----------+        +----------+
                            |
                            | (repeat)
                            v

    4. HANDOFF          5. RESTORE          6. CONTINUE
       Session             Context             Working

        [>>>]              [<<<]              [...]
          |                  |                  |
          v                  v                  v
    +----------+       +----------+        +----------+
    | Save AI  |  -->  | Load AI  |  -->   | Full     |
    | State    |       | State    |        | Context  |
    +----------+       +----------+        +----------+

Phase 1: Create World Model

Start by creating a world model - your project's knowledge container:

# CLI
create-state init --name "my-app" --language python
# Python
client.create_world_model(
    project_name="my-app",
    language="python",
    description="E-commerce backend with FastAPI"
)

This creates an empty knowledge graph ready to capture your project's evolution.

Phase 2: Capture Knowledge

Automatic with IDE Integration: When using Create State through an MCP integration, code and context are captured automatically as you work. That's our value add - you don't have to do anything.

Officially supported integrations:

  • Cursor
  • Claude
  • OpenAI
  • VS Code
  • GitHub Copilot
  • Lovable
  • Google Antigravity

Other MCP-compatible tools should also work with Create State, even if not officially tested.

CLI/SDK for Batch Capture: Use capture code to build your knowledge graph from existing code:

# Capture entire codebase (recursive) - builds knowledge graph
create-state capture code ./src

# Or filter by file types
create-state capture code ./ --extensions py,js,ts

# Single file capture
create-state capture code ./src/auth.py --description "Auth module"
    YOUR CODEBASE                     KNOWLEDGE GRAPH

    ./src/                            +--[Module]----+
    ./lib/                   -->      | 127 files    |
    ./tests/                          | 342 nodes    |
                                      | 891 edges    |
                                      +--------------+

Capture decisions and context: For architectural decisions not in code:

# Capture context via CLI
create-state capture context "Chose Redis for caching due to low latency"
# Or via Python SDK
client.capture_context(
    "Decided to use JWT for authentication because it's stateless "
    "and scales horizontally."
)

Analyze without capturing (privacy-safe exploration):

# Analyze only - nothing stored, just returns insights
create-state analyze ./src

# Analyze AND capture in one command
create-state analyze ./src --capture
Command Persists to Graph Returns Analysis
capture code <path> Yes No
analyze <path> No Yes
analyze <path> --capture Yes Yes

Phase 3: Synthesize Knowledge

Automatic: Synthesis runs automatically after every 5 captures, creating a comprehensive project summary using AI.

Manual trigger: Force immediate synthesis at natural breakpoints:

# Optional - synthesis happens automatically
create-state synthesize

This creates a comprehensive project summary:

+------------------------------------------------------------------+
|                    SYNTHESIZED PROJECT CONTEXT                    |
+------------------------------------------------------------------+
| Project: my-app                                                   |
| Language: Python 3.11                                             |
| Framework: FastAPI                                                |
|                                                                   |
| ARCHITECTURE:                                                     |
|   - REST API with JWT authentication                              |
|   - PostgreSQL for persistence                                    |
|   - Redis for caching (optional)                                  |
|                                                                   |
| KEY DECISIONS:                                                    |
|   - JWT over sessions for horizontal scaling                      |
|   - Pydantic for validation                                       |
|                                                                   |
| KNOWN ISSUES:                                                     |
|   - Token refresh not implemented yet                             |
|                                                                   |
| PRIORITIES:                                                       |
|   1. Complete auth flow                                           |
|   2. Add rate limiting                                            |
+------------------------------------------------------------------+

When to manually synthesize:

  • Before creating a session handoff (ensures latest context is included)
  • After completing a major feature
  • Before switching to different work area

Phase 4: Create Session Handoff

Before ending your session, create a handoff to preserve AI thinking state:

# CLI
create-state handoff create --name "end-of-day-jan-1"
# Python
handoff = client.create_session_handoff(
    handoff_name="end-of-day-jan-1",
    include_experimental_thoughts=True
)
print(f"Handoff ID: {handoff['handoff_id']}")

The handoff captures:

+------------------------------------------------------------------+
|                     SESSION HANDOFF PACKAGE                       |
+------------------------------------------------------------------+
|  - Active world model reference                                   |
|  - Recent captures and context                                    |
|  - AI thinking state and hypotheses                               |
|  - Pending insights not yet discussed                             |
|  - Work in progress indicators                                    |
+------------------------------------------------------------------+

Phase 5: Restore Session

When starting a new session, restore from the handoff:

# CLI - list available handoffs
create-state handoff list

# Restore from specific handoff
create-state handoff restore abc123-def456
# Python
packages = client.list_handoff_packages()
for pkg in packages.get("handoff_packages", []):
    print(f"{pkg['id']}: {pkg['name']} ({pkg['created_at']})")

# Restore
client.restore_from_handoff(handoff_id="abc123-def456")

Phase 6: Continue Working

After restoration, your AI has full context:

    BEFORE RESTORE                    AFTER RESTORE

    +----------------+                +----------------+
    | AI: "I don't   |                | AI: "I see we  |
    | know anything  |     -->        | were working   |
    | about your     |                | on JWT auth    |
    | project"       |                | yesterday..."  |
    +----------------+                +----------------+

Query your knowledge graph to find past decisions:

# AI-powered conversation (uses your LLM to generate answers)
create-state ask "why did we choose JWT for auth?"

# Direct graph search (exact matches in knowledge graph)
create-state query "authentication decisions"

# Semantic search (finds conceptually similar content)
create-state search "how does login work"
# Python - Direct graph query
result = client.query_world_model("authentication classes")

# Python - Semantic vector search
results = client.search_knowledge("JWT decision rationale")

# Python - AI-powered chat (requires BYOK or uses built-in Qwen)
response = client.ask("why did we choose JWT for auth?")

Get AI-generated insights:

# Get focused insights
create-state insights --focus security

# Get autonomous "shower thinking" insights
create-state thinking --priority high

Complete Workflow Example

Here's a typical day using the CLI (note: with Cursor/Claude Desktop integration, capture is automatic):

+==================================================================+
|                    A DAY WITH CREATE STATE                        |
+==================================================================+

MORNING - Start Session
-----------------------
$ create-state handoff list
Available handoffs:
  abc123: end-of-day-dec-31 (2025-12-31T18:00:00Z)

$ create-state handoff restore abc123
[OK] Session restored. Context loaded for: my-app
[OK] Last working on: JWT authentication flow


MIDDAY - Capture Your Codebase
------------------------------
$ create-state ask "what's the auth implementation status?"
[INFO] Based on your captured context...

# Capture entire project to knowledge graph
$ create-state capture code ./
[OK] Captured 127 files to knowledge graph
[INFO] Auto-synthesis triggered (5+ captures)


AFTERNOON - Check Insights
--------------------------
$ create-state insights --focus security
[INFO] 2 security recommendations:
  1. Consider adding rate limiting to /auth/refresh
  2. Token expiry could be configurable via env var

$ create-state thinking
[INFO] Autonomous insights:
  - The auth module has grown complex; consider splitting
  - Test coverage for edge cases is low


END OF DAY - Handoff
--------------------
$ create-state handoff create --name "end-of-day-jan-1"
[OK] Handoff created: def456-ghi789
[OK] AI state preserved for next session

Note: When using Create State through Cursor or Claude Desktop, capture happens automatically as your AI assistant works with you. The CLI is for batch operations or explicit control.


CLI Reference

Global Options

Option Description
-v, --verbose Show API parameters sent
-V, --version Show version and exit

Tip: Use -v when learning the CLI. It shows both the response and the parameters sent, helping you understand how the API works:

$ create-state -v synthesize
# Synthesizing project knowledge...

# Project Summary Synthesized

**Project:** my-project
**Summary ID:** d2877693-f0e4-47e7-837b-80bba5741ad5
**Entities Analyzed:** 210
...

PARAMETERS
  project_path: .

Without -v, only the response is shown (no PARAMETERS section).

Commands

Command Description
configure Set up API credentials
init Initialize a world model for a project (sets as active)
models List your world models
use <name-or-id> Set active world model by name or ID
status [--rendering-mode MODE] Show active model status and context
capture context "..." Capture decisions or discussions
capture code <path> Capture code to knowledge graph (file or dir)
analyze <path> Analyze code (transient, use --capture to persist)
ask <question> Get AI-generated answers using your project context
query <terms> Search knowledge graph for matching files, decisions, insights
search <terms> Semantic search using vector similarity
insights Get AI-generated project insights
thinking Get autonomous background insights
synthesize Create comprehensive knowledge summary
handoff create Create session handoff package
handoff list List available handoff packages
handoff restore <id> Restore from session handoff
auth github Connect/manage GitHub account
init --from-github <url> Import from GitHub repository
Teams Tier Commands Requires Teams or Enterprise subscription
team list List teams you belong to
team create <name> Create a new team
team show <team-id> Show team details
team members <team-id> List team members
team invite <team-id> <email> Invite user to team
team remove <team-id> <user-id> Remove member from team
team role <team-id> <user-id> <role> Update member role
team projects <team-id> List team's shared projects
team share <team-id> Share active project with team
team unshare <team-id> Remove project sharing
team activity <team-id> View team activity feed
team pulse Get team activity overview
team expert <topic> Find team experts on a topic
team colleague <email> View colleague's recent activity
team stats <email> Get contributor statistics
team capacity Get/set project working capacity
Image Commands Capture visual assets to knowledge graph
capture image <path> Capture image file to knowledge graph

GitHub Integration (NEW in v0.3.0)

Import repositories directly from GitHub to create World Models with full code analysis.

Connect GitHub (required for private repos):

# Connect via Device Flow (browser-based auth)
create-state auth github

# Check connection status
create-state auth github --status

# Disconnect
create-state auth github --disconnect

Import from GitHub:

# Import a public repository
create-state init --from-github https://github.com/owner/repo

# Import a specific branch
create-state init --from-github https://github.com/owner/repo --branch develop

# Import with custom project name
create-state init --from-github https://github.com/owner/repo --name "My Project"

The import process:

  1. Validates the GitHub URL
  2. Checks GitHub connection (for private repos)
  3. Clones and analyzes the repository server-side
  4. Creates a World Model with full code graph
  5. Sets the new model as active
$ create-state init --from-github https://github.com/fastapi/fastapi

[GitHub Import] fastapi/fastapi

# Checking GitHub connection...
[OK] GitHub connected as: your-username

# Starting import...
Importing repository.......................

[SUCCESS] GitHub import complete!

Project: fastapi
Model ID: abc123-def456
Files Imported: 342

Command Details

capture - Capture knowledge to the graph (persists data):

# Capture decisions or discussions
create-state capture context "We chose PostgreSQL for ACID compliance"

# Capture single file
create-state capture code ./src/auth.py
create-state capture code ./src/billing.py --description "Payment module" --type new

# Capture entire directory (recursive)
create-state capture code ./src
create-state capture code ./ --extensions py,js,ts --max-files 200

Options for capture code:

  • --description, -d - Description of the code or changes (single file only)
  • --language, -l - Programming language (auto-detected from extension)
  • --type, -t - Type of change: new, update, fix, refactor (default: update)
  • --max-files - Maximum files to capture for directories (default: 100)
  • --extensions - Comma-separated file extensions (default: py,js,ts,jsx,tsx)
  • --include-gitignored - Include files that would be excluded by .gitignore

analyze - Analyze code quality (transient by default):

# Analyze only - returns insights, nothing stored
create-state analyze ./src

# Analyze AND capture to knowledge graph
create-state analyze ./src --capture

# Single file analysis
create-state analyze ./src/auth.py

Options for analyze:

  • --capture - Also capture code to knowledge graph (requires active model)
  • --max-files - Maximum files to analyze (default: 100)
  • --extensions - Comma-separated file extensions
  • --include-gitignored - Include files that would be excluded by .gitignore

ask - AI-powered Q&A using your configured LLM (BYOK provider or built-in Qwen):

create-state ask "why did we choose Redis here?"
create-state ask "what patterns do we use for error handling?"
create-state ask "explain the authentication flow"

The AI receives your full project context and generates a conversational response. This is equivalent to chatting in the web UI's world model chat panel.

query - Direct graph search for code files, decisions, and captured insights:

create-state query "authentication"           # Find auth-related nodes
create-state query "payment processing"       # Search by keywords
create-state query --code "middleware"        # Include code snippets in output

Returns exact matches from your knowledge graph: CodeEntities (files), Decisions, and Insights. Searches names, file paths, and descriptions. Fast and deterministic.

search - Semantic search using vector embeddings for conceptual matching:

create-state search "how does login work"     # Finds auth-related content
create-state search "error handling patterns" # Conceptual similarity

Unlike query (exact keyword matching), search uses AI embeddings to find content that is semantically similar to your query, even if it uses different terminology.

Add --images to search screenshots and diagrams by description, OCR text, or visual similarity:

create-state search --images "login screen"
create-state search --images "architecture" --category diagram --mode semantic

node - Read or correct one knowledge node by the id that search printed:

create-state node read context_<uuid>
create-state node update decision_<uuid> --type Decision --updates '{"status": "accepted"}'

node read prints the record to stdout. node update takes the new values as a JSON object of strings. Correcting an Entity's name or type retracts the old entity and prints the id of its successor.

Teams Commands (NEW in v0.4.0)

Teams tier commands enable collaboration features. These require a Teams or Enterprise subscription.

team - Manage teams and collaboration:

# List your teams
create-state team list

# Create a new team
create-state team create "Backend Team" --description "API development"

# Show team details
create-state team show <team-id>

# List team members
create-state team members <team-id>

# Invite a member (roles: owner, admin, member, viewer)
create-state team invite <team-id> dev@example.com --role admin

# Update member role
create-state team role <team-id> <user-id> viewer

# Remove a member
create-state team remove <team-id> <user-id>

team projects - Share projects with teams:

# List projects shared with a team
create-state team projects <team-id>

# Share active project with a team
create-state team share <team-id> --permission write

# Share a specific model
create-state team share <team-id> --model <model-id>

# Remove project sharing
create-state team unshare <team-id>
create-state team unshare <team-id> --model <model-id>

team intelligence - Understand team activity:

# View team activity feed
create-state team activity <team-id> --limit 20

# Quick team overview
create-state team pulse
create-state team pulse --team <team-id>

# Find experts on a topic
create-state team expert "authentication"
create-state team expert "database optimization" --team <team-id>

# View colleague activity
create-state team colleague dev@example.com --days 14

# Get contributor stats for active project
create-state team stats dev@example.com
create-state team stats dev@example.com --model <model-id>

# Get/set working capacity
create-state team capacity                    # Show current
create-state team capacity --set <team-id>    # Set to team

Python API Reference

Client Initialization

Note: An API key is required. Get one at createstate.ai/web/api-keys

from createstate import CreateStateClient

# With explicit API key
client = CreateStateClient(api_key="cs_...")

# From environment variable CREATESTATE_API_KEY
client = CreateStateClient()

# Custom endpoint (for enterprise deployments)
client = CreateStateClient(base_url="https://your-instance.example.com")

Code Analysis

# Analyze code string
result = client.analyze_code(code, language="python")

# Analyze with educational insights
result = client.analyze_code_with_intelligence(
    code,
    include_educational_insights=True,
    include_alternatives=True
)

# Analyze local files (reads from filesystem)
result = client.analyze_file("./src/main.py")

# Analyze directory (respects .gitignore by default)
result = client.analyze_directory(
    "./src",
    max_files=100,
    respect_gitignore=True  # Default - skips gitignored files
)

World Model Operations

# Create
model = client.create_world_model("my-app", "python", "Description")

# Get context (auto-detects optimal display mode)
context = client.get_world_model()

# Get context with specific display mode
# Options: taste_topology, semantic_graph, conceptual_identity, integrated
context = client.get_world_model(rendering_mode="taste_topology")

# Query
result = client.query_world_model("authentication classes")

# List
models = client.list_world_models()

Knowledge Capture

# Capture context (decisions, discussions)
client.capture_context("Decided to use PostgreSQL for ACID compliance")

# Capture code
client.capture_code(
    code="def process_payment(): ...",
    file_path="src/billing.py",
    language="python",
    description="Payment processing function",
    change_type="new"  # new | update | fix | refactor
)

# Synthesize all knowledge
client.synthesize_context()

# Search knowledge
results = client.search_knowledge("payment processing")

Image Capture (NEW)

Capture screenshots, diagrams, and visual assets to your knowledge graph:

# Capture an image file
result = client.capture_image(
    image_data=base64_encoded_data,
    mime_type="image/png",
    title="Architecture Diagram",
    description="System architecture overview",
    category="diagram",  # screenshot | diagram | asset | other
    related_file_path="docs/architecture.md"  # Optional
)
print(f"Image ID: {result['image_id']}")

# Search for images
results = client.search_images(
    query="authentication flow",
    mode="hybrid",  # text | semantic | hybrid
    category="diagram",  # Optional filter
    limit=10
)
for img in results.get("results", []):
    print(f"{img['title']}: {img['score']}%")

CLI:

# Capture an image file
create-state capture image ./screenshots/error.png --title "Login Error"
create-state capture image ./diagrams/arch.png --title "Architecture" --category diagram

# Images are automatically processed with:
# - Vision AI for description generation
# - OCR for text extraction
# - CLIP embeddings for semantic search

Session Handoff

# Create handoff
handoff = client.create_session_handoff(handoff_name="end-of-sprint")

# List handoffs
packages = client.list_handoff_packages()

# Restore
client.restore_from_handoff(handoff_id="abc123")

Insights

# Proactive insights
insights = client.get_insights(focus_area="security")

# Autonomous insights
insights = client.get_shower_thinking_insights(priority_filter="high")

GitHub Integration (NEW in v0.3.0)

# Check if GitHub is connected
status = client.github_status()
if status["connected"]:
    print(f"Connected as {status['username']}")

# Connect GitHub (interactive - opens browser)
result = client.github_connect()
print(f"Connected as {result['username']}")

# Import a repository
result = client.github_import(
    repo_url="https://github.com/owner/repo",
    project_name="My Project",
    branch="main",  # Optional
    wait=True,      # Wait for completion (default)
    progress_callback=lambda p: print(f"{p['progress']}% - {p['message']}")
)
print(f"Model ID: {result['model_id']}")
print(f"Files: {result['files_imported']}")

# Import without waiting (async)
job = client.github_import(
    "https://github.com/owner/repo",
    "My Project",
    wait=False
)
# Poll manually
status = client.github_import_status(job["job_id"])
print(f"{status['progress']}% complete")

# Cancel an import
client.github_import_cancel(job["job_id"])

# Disconnect GitHub
client.github_disconnect()

Teams Features (NEW in v0.4.0)

Teams tier features enable collaboration across your organization. These methods require a Teams or Enterprise subscription.

# =============================================================================
# Team Management
# =============================================================================

# List teams you belong to
teams = client.list_teams()
for team in teams.get("teams", []):
    print(f"{team['id']}: {team['name']}")

# Create a new team
team = client.create_team(
    name="Backend Team",
    description="API and services team"
)
print(f"Created team: {team['team_id']}")

# Get team details
details = client.get_team_details(team_id="team-123")

# =============================================================================
# Member Management
# =============================================================================

# List team members
members = client.list_team_members(team_id="team-123")

# Invite a user (roles: owner, admin, member, viewer)
client.invite_to_team(
    team_id="team-123",
    email="dev@example.com",
    role="member"  # Default role
)

# Update member role
client.update_member_role(
    team_id="team-123",
    user_id="user-456",
    role="admin"
)

# Remove member
client.remove_team_member(team_id="team-123", user_id="user-456")

# =============================================================================
# Project Sharing
# =============================================================================

# Share a project with a team (permissions: read, write, admin)
client.share_project_with_team(
    team_id="team-123",
    world_model_id="model-456",
    world_model_name="My API Project",
    permission="write"  # Default is "read"
)

# List projects shared with a team
projects = client.list_team_projects(team_id="team-123")

# Remove sharing
client.unshare_project_from_team(
    team_id="team-123",
    world_model_id="model-456"
)

# =============================================================================
# Working Capacity
# =============================================================================

# Get who's currently working on a project
capacity = client.get_working_capacity(world_model_id="model-456")
print(f"Current team: {capacity.get('team_name', 'Personal')}")

# Set working capacity to a team
client.set_working_capacity(
    world_model_id="model-456",
    team_id="team-123"  # Omit for personal capacity
)

# =============================================================================
# Team Intelligence
# =============================================================================

# Get team activity feed
activity = client.get_team_activity(team_id="team-123", limit=20)

# Quick team overview (pulse)
pulse = client.get_team_pulse(
    team_id="team-123",      # Optional - filter by team
    world_model_id="model-456"  # Optional - filter by project
)

# Find experts on a topic
experts = client.find_topic_expert(
    topic="authentication",
    team_id="team-123"  # Optional - search within team
)
for expert in experts.get("experts", []):
    print(f"{expert['name']}: {expert['expertise_score']}")

# View colleague's recent activity
activity = client.get_colleague_activity(
    colleague_email="dev@example.com",
    days=14  # Default is 7
)

# Get contributor statistics for a project
stats = client.get_contributor_stats(
    contributor_email="dev@example.com",
    world_model_id="model-456"
)

# Search contributions by a specific person
results = client.search_by_contributor(
    contributor_email="dev@example.com",
    entity_types=["code", "decision"],  # Optional filter
    start_date="2026-01-01",            # Optional
    limit=50
)

Error Handling

from createstate import (
    CreateStateError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
)

try:
    result = client.analyze_code(code)
except AuthenticationError:
    print("Invalid API key - get one at createstate.ai/web/api-keys")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Invalid input: {e.message}")
except CreateStateError as e:
    print(f"API error: {e}")

Configuration

Environment Variables

Variable Description
CREATESTATE_API_KEY Your API key (required)
CREATESTATE_API_URL Custom API URL (optional)

Config File

Stored at ~/.createstate/config.json:

{
  "api_key": "cs_your_api_key",
  "api_url": "https://createstate.ai",
  "active_model": {
    "id": "d8e850c0-e8e4-42e7-ac47-361605bcb938",
    "name": "My Project"
  }
}
  • Run create-state configure to set up API credentials
  • The active_model is automatically set when you run create-state init
  • Use create-state use <name-or-id> to switch active models (names and partial IDs work)
  • Use create-state models to list available models

Security & Privacy

Data Persistence: Analyze vs Capture

Understanding which commands store data is important for privacy:

Command Data Stored? Use Case
analyze <path> No Safe exploration, quality insights
analyze <path> --capture Yes Explore + persist to graph
capture code <path> Yes Build knowledge graph
capture context "..." Yes Record decisions

Privacy-safe exploration: Use analyze without --capture to explore code quality, detect patterns, and get insights without storing anything.

Respecting .gitignore

Both analyze and capture code respect your .gitignore by default. Files that Git would ignore are automatically skipped, protecting:

  • .env files containing secrets and API keys
  • Local configuration files with credentials
  • Build artifacts and generated code
  • Dependency directories (node_modules, venv, etc.)
# Default behavior - respects .gitignore
create-state capture code ./
create-state analyze ./

# Override to include gitignored files (use with caution)
create-state capture code ./ --include-gitignored
create-state analyze ./ --include-gitignored

In Python:

# Control gitignore behavior
result = client.analyze_directory(
    "./src",
    respect_gitignore=True,  # Default
)
print(f"Files gitignored: {result['files_gitignored']}")

File Type Restrictions

The SDK only analyzes recognized source code files. Binaries, images, and data files are automatically skipped.

Credential Protection

Your API key is stored in ~/.createstate/config.json with restricted file permissions. API keys are never logged or included in error messages.

Data Transmission

The analyze_file() and analyze_directory() functions read files from your local filesystem and transmit their contents to Create State servers for analysis. See our Privacy Policy for details.

License

MIT License - Copyright (c) 2026 Create State. All rights reserved.

See LICENSE for details.

Metadata

Release files for createstate 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for createstate 0.6.0
File Size Uploaded
createstate-0.6.0.tar.gz 73.9 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for createstate 0.6.0
File Interpreter ABI Platform
createstate-0.6.0-py3-none-any.whl Python 3 none any Details

Total release size: 129.0 kB

Release files / createstate-0.6.0.tar.gz

Download URL createstate-0.6.0.tar.gz
Size 73.9 kB
Tags Source
SHA-256 checksum
How to use checksums
d8143ed5fa9ac01193a0bc3bf2b21f3bd83a5661289fa9e0edc46e9d7406c31c
BLAKE2b-256 checksum
How to use checksums
6758a410dd389afe935f1676ce8387a0df1c78e677cad2073a631e4c3c39de39
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.12

Release files / createstate-0.6.0-py3-none-any.whl

Download URL createstate-0.6.0-py3-none-any.whl
Size 55.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d00e4150ee73580e174f71bd54cc4e9868c510b5f935bfaee032991904b01aa5
BLAKE2b-256 checksum
How to use checksums
394ed0bc077a7fa3add268046eb87e801f82a3c5c85487fdc20eb4b5d916334d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.12

Release history Release notifications | RSS feed

This release

0.6.0 This release

2 release files

0.3.10

2 release files

0.1.25

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page