innoday 0.1.42b0

AI-Powered Team Orchestration Platform - Streamline product development and team collaboration with AI

InnoDay Platform

InnoDay is the central hub of your project. Every significant event — ticket work, releases, spec changes, board syncs, repo additions, meeting decisions — is recorded here. Skills, agents, and CLI tools all write back to InnoDay so that the full history of a project is always queryable in one place.

AI-powered development platform for managing tickets, boards, repositories, and releases with Claude AI integration.

🚀 Quick Start

Most people just need the CLI, pointed at the shared dev environment — not a repo clone or a self-hosted platform.

# Install the CLI from PyPI
uv tool install innoday

# Register against the shared dev environment (Railway-hosted)
innoday init --default
# Defaults to https://innoday-dev.up.railway.app -- no --api-url needed for
# dev. Prompts for the team access secret interactively. --default persists
# this as the profile used automatically (including for MCP).

# Verify end-to-end
innoday orgs list
# Should list your accessible organizations with exit code 0.

Only clone this repo and run a platform yourself if you're standing up your own instance (self-hosting, or local development on InnoDay itself) — see Running Your Own Platform below.

🤖 Claude Code MCP Integration

Add InnoDay directly to Claude Code — create tickets, sync boards, and query work items without leaving your editor. Reuses the CLI config from Quick Start above once innoday init has been run.

claude mcp add innoday -- uvx --from innoday mcp-server-innoday

Or find it in the MCP registry: io.github.havilandsoftware/mcp-server-innoday

See CLAUDE.md for the full MCP tool reference — this README doesn't maintain a second hand-written tool list to avoid the two drifting out of sync.

Environment variables (optional):

Variable	Default	Description
INNODAY_API_URL	https://innoday-dev.up.railway.app	URL of your InnoDay instance — matches innoday init's own default (the shared dev environment); override to point at a local instance instead
INNODAY_TEAM_SECRET	(from ~/.innoday/config.json)	Overrides the X-Team-Secret header sent on every request; only needed against a TEAM_ACCESS_SECRET-gated deployment (see CLAUDE.md's "Optional (deployed environments)")

Org/project context for MCP tool calls is not set via an env var — like the CLI, the MCP server resolves it from .innoday/project.yml in the directory Claude Code was launched from (see Config & Project Setup below), falling back to your last-used org from ~/.innoday/config.json. Pass organization_id/project_id explicitly to a tool call to override either for that one call.

Troubleshooting: MCP tools failing with a stale error after a fix ships

If mcp__innoday__* tool calls keep failing the same way even after a fix merges and publishes to PyPI, the installed CLI/MCP binary itself is stale — claude mcp add/reconnect does not re-fetch code, it just reconnects to whatever uvx --from innoday mcp-server-innoday currently resolves to. uvx and uv tool upgrade both resolve "latest" by version-number comparison, which can pin to an old release if that release's number is numerically higher than the current line (see "Reset history" in docs/VERSION_MANAGEMENT.md) or if it's simply cached from a prior uv tool install.

Fix, in order:

uv tool list | grep innoday          # compare against the version that just published
uv tool upgrade innoday --reinstall  # --reinstall bypasses uv's own version comparison,
                                      # which is necessary if the prior install predates
                                      # a version-numbering reset

Then reconnect the MCP session (/mcp reconnect in Claude Code, or restart the session) — the running MCP server process is spawned once and never re-reads the binary on its own.

🗂️ Config & Project Setup

Two different files are involved, at two different scopes — worth keeping straight:

File	Scope	What it holds
~/.innoday/config.json	Your machine, all projects	Identity: current profile, API URL, your user id, last-used org, which integrations are configured. Written by innoday init/config init. Integration secrets are never stored here — this file only holds a pointer to where the real value lives (your system keyring for GitHub tokens and legacy board credentials; Supabase Vault, server-side, for newer Jira/Trello/Linear board credentials).
<workspace>/.innoday/project.yml	One specific project workspace	Which org + project this directory belongs to (org.slug, org.innoday_id, project.innoday_id), plus the repos that make it up. Created by onboarding a project (see pixelfuel-claude's register-project/onboard-project skills, or hand-authored for a non-Pixelfuel workspace).

How org/project context actually gets resolved, both for the CLI and the MCP server, in precedence order:

1. An explicit override for this one call — --organization <slug> for the CLI, or organization_id/project_id arguments on an MCP tool call.
2. .innoday/project.yml, found by walking up from the current directory. This is why running innoday (or launching Claude Code with the MCP server) from inside a project workspace resolves the right org/project automatically, with zero flags.
3. The last-used org persisted in ~/.innoday/config.json, as a fallback for commands run outside any project directory (e.g. a bare innoday orgs list from your home directory).

There is no persistent "switch" command for either the CLI or MCP — a directory's own .innoday/project.yml always wins over whatever org you used last, so moving between project workspaces resolves correctly without remembering to switch anything.

The object model, from the top down:

• Organization — the tenant/security boundary. Everything below is isolated by org. Most day-to-day work never touches this directly.
• Project — the unit you actually work inside. Has a slug (used to match GitHub repos by topic label), a scope document, and exactly one board. .innoday/project.yml pins a workspace to one project.
• Board — one Jira/Trello/Notion/Linear board, synced into a project. A board always belongs to exactly one project (enforced at the database level) — this is where tickets originate from.
• Ticket — a work item, always belonging to a project (via its board). Created either by a board sync or directly via innoday tickets create (InnoDay-only until a board sync or explicit push reconciles it externally).
• Repository — tracked against a project by GitHub topic label (innoday git sync), not manually linked one at a time.
• Release — a version record tied to a project, created by blastoff or innoday releases create.

📇 CLI Reference

Every command below is verified against the current CLI (src/cli/commands/) — none of these are aspirational. Run innoday <command> --help for the full flag list on anything.

# Identity & setup
innoday init --default          # First-time setup, registers against dev by default
innoday config init              # Re-run the interactive setup wizard
innoday config show               # View current config
innoday config set api-url <url>  # Point the CLI at a different InnoDay instance
innoday config integrations       # Configure Jira/Trello/Notion credentials
innoday orgs list                 # List organizations you can access
innoday orgs current              # Show the org resolved for this invocation
innoday orgs show [slug] [--stats]
innoday orgs env-setup [slug]     # Wizard for env/orgs/<slug> board credentials
innoday version                   # CLI version

# Org/project context is resolved from cwd, not a persistent "switch" command --
# run bare `innoday` commands from inside a directory with .innoday/project.yml
# and org/project resolve automatically. Use --organization <slug> only to
# override when running outside any project directory.

# Projects (the unit you work inside day to day)
innoday projects create "Customer Portal" --description "Q1 features"
innoday projects list
innoday projects show --project-id <id> [--overview]
innoday projects update --project-id <id> --status ACTIVE
innoday projects delete --project-id <id>

# Tickets
innoday tickets list
innoday tickets create "New feature"
innoday tickets show --ticket-id <id>
innoday tickets update --ticket-id <id> --status IN_PROGRESS
innoday tickets assign --ticket-id <id> <user-id>
innoday tickets close --ticket-id <id>
innoday tickets comment --ticket-id <id> "note"
innoday tickets comments --ticket-id <id>

# Boards (Jira / Trello / Notion / Linear)
innoday board register --type jira "<board-url>" "Board Name" --project-id <id>
innoday board sync --board-id <id>

# Scope documents
innoday scope show <project-id>
innoday scope generate <project-id>

# Sync — the project-scoped cascade (board tickets, repo discovery, release status)
innoday sync                      # Cascade sync using cwd's project context
innoday sync ticket <PROJ-123>    # Fetch/upsert one ticket immediately by external key

# Repository discovery (topic-based, project-scoped)
innoday git sync [--org <slug>] [--project-id <id>] [--label <topic>]

# Board credential storage (Trello/Jira tokens specifically -- not general auth)
innoday auth login [--service trello|jira]
innoday auth status
innoday auth list

Service management (innoday status, no prefix, is a real identity/connectivity check — distinct from platform status below):

innoday status                            # Check CLI identity + API connectivity
innoday platform init                      # Interactive platform setup wizard
innoday platform start --env <local|dev|test>
innoday platform stop
innoday platform restart
innoday platform logs
innoday platform status

The old bare innoday start/stop/restart/logs (no platform prefix) still work as deprecated shims for the commands above — use the platform-prefixed form. Neither form has an agent service; only api, ui, and all exist.

🔧 Running Your Own Platform

Only needed if you're self-hosting InnoDay or developing on this repo itself — most users want the Quick Start above instead.

git clone [e-mail]:havilandsoftware/innoday.git
cd innoday
./install.sh
innoday platform init   # Interactive setup wizard (new terminal)

Full walkthrough — prerequisites, database setup, environment variables, verification, platform staff roles, known limitations — lives in docs/PLATFORM_SETUP.md. That guide is the canonical copy; this README doesn't duplicate it.

Other ways to run it:

No installation — run from the cloned repo directly

git clone https://github.com/havilandsoftware/innoday.git
cd innoday
./bin/innoday --version   # Wrapper: cd's to repo root, runs via uv, no install step

cat > .env.local <<'EOF'
ENVIRONMENT=local
DATABASE_URL=postgresql://innoday:innoday_pass@localhost:54322/innoday
CLAUDE_API_KEY=your-claude-api-key
GITHUB_TOKEN=your-github-token
GITHUB_ORG=havilandsoftware
EOF

./bin/innoday platform start --env local

Docker Compose

git clone https://github.com/havilandsoftware/innoday.git
cd innoday
docker compose up -d

Service URLs (local): REST API http://localhost:8002 (docs) · Agent API http://localhost:9000 · Web UI http://localhost:7860

Uninstall:

./uninstall.sh
# Or manually:
rm -rf ~/.innoday
rm -f ~/.local/bin/innoday
# Then remove the PATH entry for ~/.local/bin from your shell config

✨ Features That Make InnoDay Special

🤖 AI-Powered Team Orchestration

• Smart Update Collection: Automatically gather and summarize team progress with AI assistance
• Intelligent Meeting Preparation: AI-driven SCRUM facilitation and meeting insights
• Optimal Workload Distribution: Machine learning-based task assignment and team balancing
• Context-Aware Information Routing: Connect people to the right information at the right time
• Claude AI Integration: Advanced conversation analysis with recency weighting and temporal patterns

🗂️ InnoDay as the Central Hub

InnoDay is not just a ticket tracker — it is the authoritative record of everything that happens on a project. All platform tools are designed to write back to InnoDay so that history, decisions, and state are always queryable without having to reconstruct them from git logs or local files.

Event	How it reaches InnoDay
Ticket created / status changed	CLI innoday tickets create/update, MCP create_ticket, update_ticket
Release cut	blastoff release registers the release record automatically
Board synced, ticket carries a new release/fix-version	BoardSyncService._ensure_release_exists auto-creates a PLANNED release row (version taken from the synced ticket's fix-version field, not hardcoded) — triggered during board sync, not project onboarding
Repo tracked for a project	innoday git sync discovers repos by GitHub topic label and reconciles them against the project
Spec / goals updated	MCP update_project_scope; CLI equivalent is innoday scope show/innoday scope generate
Meeting or decision	MCP add_project_update
Board sync	MCP sync_board, sync_linear_board
Agent session output	MCP add_project_update — any output worth keeping goes here, not only to local memory

Rule of thumb: if you need to remember it across sessions or share it with the team, save it to InnoDay. Local .innoday/memory.json is a cache; InnoDay is the record of truth.

📁 Project-Based Organization

Project is the unit you actually work inside day to day — the thing you cd into, register boards for, and sync tickets against. Organization exists underneath as the tenant/security boundary (see "Enterprise-Ready Architecture" below), not something you interact with directly most of the time.

• Unified Project Structure: Organize work with goals, scope, and clear boundaries
• Scope Document Management: Version-controlled requirements with iterative refinement workflow
• Project Update Tracking: Capture clarifications, feedback, and Q&A during scoping
• Repository Layer Classification: Categorize repos by architecture (UI, API, Data, AI, Legacy)
• Primary Repository Designation: Identify the main codebase for each project
• Board Association: Every board belongs to exactly one project — enforced at the database level (BoardRegistration.project_id is a required FK) — and the same rule applies to repositories.
• Release Records: Every release is registered in InnoDay with version, status, summary, and changelog
• Project Overview Dashboard: Complete visibility across all project components

🔗 Unified Multi-Platform Integration

• Central Hub: InnoDay receives events from all connected tools — boards, repos, agents, and the CLI
• Single Source of Truth: Seamlessly manage Jira, Trello, Notion, Linear, and GitHub from one interface
• Real-Time Synchronization: Automatic bi-directional sync with intelligent duplicate detection
• Universal Ticket Model: Work with tickets from any platform using consistent APIs — including the unified GET /work endpoint
• Linear Integration: Full GraphQL sync for Linear teams, issues, workflow states, priorities, and parent relationships
• Board Registration System: Secure, token-based integration without storing credentials

🏢 Enterprise-Ready Architecture

Organization is the tenant/security boundary — the thing every Project, board, and ticket is isolated by underneath the surface, but not something you typically think about day to day once you're working inside a project.

• Organization-Based Multi-Tenancy: Complete data isolation with flexible membership roles
• Platform Organization Protection: Special administrative entity that cannot be modified or deleted
• Smart License Management: Usage-based tiers with real-time tracking and enforcement
• Role-Based Access Control: Granular permissions (MEMBER, ADMIN, OWNER, DEVELOPER, PLATFORM)

🎯 Developer Experience

• Comprehensive CLI: Rich command-line interface with secure credential storage and beautiful output
• Modern API Design: FastAPI with automatic documentation, type safety, and async support
• Three Service Architecture: Separate API, Agent, and UI services for flexible deployment
• Container Execution Support: Run AI workloads in isolated Docker environments

🏗️ API Architecture (v1)

• 144 RESTful Endpoints: Organized across 17 specialized routers
• Organization-Scoped Resources: All operations under /api/v1/organizations/{org_id}/
• Consolidated Routers: Reduced from 20+ files to 17 well-organized modules
• Unified AI Operations: All Claude/AI functionality under /api/v1/ai/
• Complete Workflows: Project management, board sync, repository tracking, and container execution

🛡️ Security & Compliance

• Token Pass-Through: Integration credentials never stored in database
• Secure Credential Management: System keyring integration for sensitive data
• Audit Trail: Complete history for synchronization, license changes, and executions
• API Protection: Platform organization endpoints restricted to authorized users

📋 Prerequisites

Only needed for Running Your Own Platform — the Quick Start path above only needs uv.

• Python 3.11+ (Required for full functionality and type safety)
• uv package manager (Install Guide)
• Database: PostgreSQL (production) or SQLite (development)
  • PostgreSQL requires psycopg2-binary (automatically installed via uv sync)
• Integration Accounts: Jira, Trello, GitHub, Claude AI, Slack (optional)

📖 Documentation

• Platform Setup Guide - Full self-hosting walkthrough: prerequisites, database, environment variables, verification
• API v1 Workflows - Complete API workflows and examples
• REST API Documentation - Comprehensive endpoint reference
• Agent API Documentation - AI agent interaction guide
• CLI Documentation - Command-line interface guide
• Integration Testing Guide - Complete testing setup and configuration
• Contributing Guide - Development setup and contribution guidelines
• Domain Model - Core business objects and relationships
• Version Management - Release and versioning process
• CI/CD Pipeline - Automated testing and deployment
• Changelog - Version history and changes

🧪 Development & Testing

Running Tests

# Full test suite
uv run python -m pytest tests/ -v

# Specific test categories
uv run python -m pytest tests/test_api* -v      # API tests
uv run python -m pytest tests/test_cli* -v      # CLI tests
uv run python -m pytest tests/test_agent* -v    # Agent tests

# Coverage report
uv run python -m pytest tests/ --cov=src --cov-report=html

Code Quality

# Format code
uv run black src/ tests/
uv run isort src/ tests/

# Lint code
uv run flake8 src/ tests/
uv run bandit -r src/

# Type checking
uv run mypy src/

🏗️ Architecture

InnoDay follows a modular architecture with clear separation of concerns:

src/
├── api/              # REST API & external integrations
├── agent/            # AI agent with HuggingFace integration
├── cli/              # Command-line interface
├── domain/           # Core business models (User, Ticket, Organization, Project)
├── middleware/       # RBAC, authentication, validation
├── routers/          # FastAPI route handlers
├── services/         # Business logic layer (ProjectService, etc.)
├── tools/            # AI-powered automation utilities
├── ui/               # Gradio web interface
└── main.py          # Service dispatcher

Key Technologies:

• FastAPI: Modern, fast web framework with automatic API docs
• SQLModel: Type-safe ORM with Pydantic integration
• HuggingFace: AI agent capabilities and model integration
• Gradio: Interactive web interface for AI interactions
• Rich: Beautiful terminal output and CLI experience

Platform Organization

InnoDay uses a special Platform Organization that serves as the system administrator:

• Singleton Entity: Only one platform organization exists per InnoDay instance
• Special Privileges: Members with PLATFORM role have cross-organization access
• Protected Entity: Cannot be modified or deleted through standard API endpoints
• System Configuration: Holds platform-wide settings and billing information
• First-time Setup: Automatically created during innoday config init

The platform organization ensures proper system administration while maintaining security boundaries between client organizations. All system-level operations and platform management require PLATFORM role membership.

🔒 Security & Licensing

Role-Based Access Control

• Admin Users: Full system access, user management, license control
• Member Users: Standard ticket and project access
• Developer Users: Repository and project management capabilities
• Organization Isolation: Multi-tenant data separation and security

Licensing Tiers

• Pro: 1 user, 1 project, 3 tickets/day, email support
• Max: 5 users, 5 projects, unlimited tickets, priority support
• Unlimited: No restrictions, priority support

Haviland Software Clients

• Free License: Included with Haviland Software services
• Full Access: Complete platform capabilities for employees

🚢 CI/CD & Deployment

The project includes comprehensive GitHub Actions workflows:

• CI Pipeline: Tests, builds, security scans, Docker
• Version Bump & Release: Auto-bumps version on merge to main, publishes to PyPI and MCP registry, creates GitHub release
• Dependency Updates: Weekly security and package updates

Release Process (fully automated):

Every merge to main automatically:

1. Bumps the minor version in src/version.py
2. Builds and publishes the package to PyPI
3. Updates server.json version and publishes to the MCP registry
4. Creates a GitHub release with changelog

Required GitHub secrets (set once):

• PYPI_API_TOKEN — PyPI API token for the innoday package

MCP registry publishing authenticates via mcp-publisher login github-oidc, using the workflow's own GitHub Actions OIDC identity (id-token: write permission) — no stored secret needed.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Standards:

• Python 3.11+ for type safety and performance
• Black code formatting and isort imports
• Comprehensive test coverage (pytest)
• Type hints with mypy validation
• Clear documentation and examples

📞 Support

• Documentation: API Docs | Agent API
• Issues: GitHub Issues
• Email: [e-mail]
• Enterprise: Contact for custom deployments and integrations

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

---

Built with ❤️ by Haviland Software