Core

Core is a Web3 Framework, written in Go using Wails.io to replace Electron and the bloat of browsers that, at their core, still live in their mum's basement.

Repo: https://forge.lthn.ai/core/cli

Vision

Core is an opinionated Web3 desktop application framework providing:

Service-Oriented Architecture - Pluggable services with dependency injection
Encrypted Workspaces - Each workspace gets its own PGP keypair, files are obfuscated
Cross-Platform Storage - Abstract storage backends (local, SFTP, WebDAV) behind a Medium interface
Multi-Brand Support - Same codebase powers different "hub" apps (AdminHub, ServerHub, GatewayHub, DeveloperHub, ClientHub)
Built-in Crypto - PGP encryption/signing, hashing, checksums as first-class citizens

Mental model: A secure, encrypted workspace manager where each "workspace" is a cryptographically isolated environment. The framework handles windows, menus, trays, config, and i18n.

CLI Quick Start

# 1. Install Core
go install forge.lthn.ai/core/cli/cmd/core@latest

# 2. Verify environment
core doctor

# 3. Run tests in any Go/PHP project
core go test   # or core php test

# 4. Build and preview release
core build
core ci

For more details, see the User Guide.

Framework Quick Start (Go)

import core "forge.lthn.ai/core/cli/pkg/framework/core"

app, err := core.New(
  core.WithServiceLock(),
)

Prerequisites

Go 1.25+
Node.js
Wails v3
Task

Development Workflow (TDD)

task test-gen    # 1. Generate test stubs
task test        # 2. Run tests (watch them fail)
# 3. Implement your feature
task test        # 4. Run tests (watch them pass)
task review      # 5. CodeRabbit review

Building & Running

# GUI (Wails)
task gui:dev      # Development with hot-reload
task gui:build    # Production build

# CLI
task cli:build    # Build to cmd/core/bin/core
task cli:run      # Build and run

Configuration

Core uses a layered configuration system where values are resolved in the following priority:

Command-line flags (if applicable)
Environment variables
Configuration file
Default values

Configuration File

The default configuration file is located at ~/.core/config.yaml.

Format

The file uses YAML format and supports nested structures.

# ~/.core/config.yaml
dev:
  editor: vim
  debug: true

log:
  level: info

Environment Variables

Layered Configuration Mapping

Any configuration value can be overridden using environment variables with the CORE_CONFIG_ prefix. After stripping the CORE_CONFIG_ prefix, the remaining variable name is converted to lowercase and underscores are replaced with dots to map to the configuration hierarchy.

Examples:

CORE_CONFIG_DEV_EDITOR=nano maps to dev.editor: nano
CORE_CONFIG_LOG_LEVEL=debug maps to log.level: debug

Common Environment Variables

Variable	Description
`CORE_DAEMON`	Set to `1` to run the application in daemon mode.
`NO_COLOR`	If set (to any value), disables ANSI color output.
`MCP_ADDR`	Address for the MCP TCP server (e.g., `localhost:9100`). If not set, MCP uses Stdio.
`COOLIFY_TOKEN`	API token for Coolify deployments.
`AGENTIC_TOKEN`	API token for Agentic services.
`UNIFI_URL`	URL of the UniFi controller (e.g., `https://192.168.1.1`).
`UNIFI_INSECURE`	Set to `1` or `true` to skip UniFi TLS verification.

All Tasks

Task	Description
`task test`	Run all Go tests
`task test-gen`	Generate test stubs for public API
`task check`	go mod tidy + tests + review
`task review`	CodeRabbit review
`task cov`	Run tests with coverage report
`task cov-view`	Open HTML coverage report
`task sync`	Update public API Go files

Architecture

Project Structure

.
├── main.go              # CLI application entry point
├── pkg/
│   ├── framework/core/  # Service container, DI, Runtime[T]
│   ├── crypt/           # Hashing, checksums, PGP
│   ├── io/              # Medium interface + backends
│   ├── help/            # In-app documentation
│   ├── i18n/            # Internationalization
│   ├── repos/           # Multi-repo registry & management
│   ├── agentic/         # AI agent task management
│   └── mcp/             # Model Context Protocol service
├── internal/
│   ├── cmd/             # CLI command implementations
│   └── variants/        # Build variants (full, minimal, etc.)
└── go.mod               # Go module definition

Service Pattern (Dual-Constructor DI)

Every service follows this pattern:

// Static DI - standalone use/testing (no core.Runtime)
func New() (*Service, error)

// Dynamic DI - for core.WithService() registration
func Register(c *core.Core) (any, error)

Services embed *core.Runtime[Options] for access to Core() and Config().

IPC/Action System

Services implement HandleIPCEvents(c *core.Core, msg core.Message) error - auto-discovered via reflection. Handles typed actions like core.ActionServiceStartup.

Wails v3 Frontend Bindings

Core uses Wails v3 to expose Go methods to a WebView2 browser runtime. Wails automatically generates TypeScript bindings for registered services.

Documentation: Wails v3 Method Bindings

How It Works

Go services with exported methods are registered with Wails
Run wails3 generate bindings (or wails3 dev / wails3 build)
TypeScript SDK is generated in frontend/bindings/
Frontend calls Go methods with full type safety, no HTTP overhead

Current Binding Architecture

// cmd/core-gui/main.go
app.RegisterService(application.NewService(coreService))  // Only Core is registered

Problem: Only Core is registered with Wails. Sub-services (crypt, workspace, display, etc.) are internal to Core's service map - their methods aren't directly exposed to JS.

Currently exposed (see cmd/core-gui/public/bindings/):

// From frontend:
import { ACTION, Config, Service } from './bindings/forge.lthn.ai/core/cli/pkg/core'

ACTION(msg)              // Broadcast IPC message
Config()                 // Get config service reference
Service("workspace")     // Get service by name (returns any)

NOT exposed: Direct calls like workspace.CreateWorkspace() or crypt.Hash().

Configuration Management

Core uses a centralized configuration service implemented in pkg/config, with YAML-based persistence and layered overrides.

The pkg/config package provides:

YAML-backed persistence at ~/.core/config.yaml
Dot-notation key access (for example: cfg.Set("dev.editor", "vim"), cfg.GetString("dev.editor"))
Environment variable overlay support (env vars can override persisted values)
Thread-safe operations for concurrent reads/writes

Application code should treat pkg/config as the primary configuration mechanism. Direct reads/writes to YAML files should generally be avoided from application logic in favour of using this centralized service.

Project and Service Configuration Files

In addition to the centralized configuration service, Core uses several YAML files for project-specific build/CI and service configuration. These live alongside (but are distinct from) the centralized configuration:

Project Configuration (in the .core/ directory of the project root):
- build.yaml: Build targets, flags, and project metadata.
- release.yaml: Release automation, changelog settings, and publishing targets.
- ci.yaml: CI pipeline configuration.
Global Configuration (in the ~/.core/ directory):
- config.yaml: Centralized user/framework settings and defaults, managed via pkg/config.
- agentic.yaml: Configuration for agentic services (BaseURL, Token, etc.).
Registry Configuration (repos.yaml, auto-discovered):
- Multi-repo registry definition.
- Searched in the current directory and its parent directories (walking up).
- Then in ~/Code/host-uk/repos.yaml.
- Finally in ~/.config/core/repos.yaml.

Format

All persisted configuration files described above use YAML format for readability and nested structure support.

The IPC Bridge Pattern (Chosen Architecture)

Sub-services are accessed via Core's IPC/ACTION system, not direct Wails bindings:

// Frontend calls Core.ACTION() with typed messages
import { ACTION } from './bindings/forge.lthn.ai/core/cli/pkg/core'

// Open a window
ACTION({ action: "display.open_window", name: "settings", options: { Title: "Settings", Width: 800 } })

// Switch workspace
ACTION({ action: "workspace.switch_workspace", name: "myworkspace" })

Each service implements HandleIPCEvents(c *core.Core, msg core.Message) to process these messages:

// pkg/display/display.go
func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
    switch m := msg.(type) {
    case map[string]any:
        if action, ok := m["action"].(string); ok && action == "display.open_window" {
            return s.handleOpenWindowAction(m)
        }
    }
    return nil
}

Why this pattern:

Single Wails service (Core) = simpler binding generation
Services remain decoupled from Wails
Centralized message routing via ACTION()
Services can communicate internally using same pattern

Current gap: Not all service methods have IPC handlers yet. See HandleIPCEvents in each service to understand what's wired up.

Generating Bindings

Wails v3 bindings are typically generated in the GUI repository (e.g., core-gui).

wails3 generate bindings    # Regenerate after Go changes

Service Interfaces (`pkg/framework/core/interfaces.go`)

type Config interface {
    Get(key string, out any) error
    Set(key string, v any) error
}

type Display interface {
    OpenWindow(opts ...WindowOption) error
}

type Workspace interface {
    CreateWorkspace(identifier, password string) (string, error)
    SwitchWorkspace(name string) error
    WorkspaceFileGet(filename string) (string, error)
    WorkspaceFileSet(filename, content string) error
}

type Crypt interface {
    EncryptPGP(writer io.Writer, recipientPath, data string, ...) (string, error)
    DecryptPGP(recipientPath, message, passphrase string, ...) (string, error)
}

Current State (Prototype)

Working

Package	Notes
`pkg/framework/core`	Service container, DI, thread-safe - solid
`pkg/config`	Layered YAML configuration, XDG paths - solid
`pkg/crypt`	Hashing, checksums, symmetric/asymmetric - solid, well-tested
`pkg/help`	Embedded docs, full-text search - solid
`pkg/i18n`	Multi-language with go-i18n - solid
`pkg/io`	Medium interface + local backend - solid
`pkg/repos`	Multi-repo registry & management - solid
`pkg/agentic`	AI agent task management - solid
`pkg/mcp`	Model Context Protocol service - solid

Package Deep Dives

pkg/crypt

The crypt package provides a comprehensive suite of cryptographic primitives:

Hashing & Checksums: SHA-256, SHA-512, and CRC32 support.
Symmetric Encryption: AES-GCM and ChaCha20-Poly1305 for secure data at rest.
Key Derivation: Argon2id for secure password hashing.
Asymmetric Encryption: PGP implementation in the pkg/crypt/openpgp subpackage using github.com/ProtonMail/go-crypto.

pkg/io - Storage Abstraction

type Medium interface {
    Read(path string) (string, error)
    Write(path, content string) error
    EnsureDir(path string) error
    IsFile(path string) bool
    FileGet(path string) (string, error)
    FileSet(path, content string) error
}

Implementations: local/, sftp/, webdav/

Future Work

Phase 1: Core Stability

~~Fix workspace medium injection (critical blocker)~~
~~Initialize io.Local global~~
~~Clean up dead code (orphaned vars, broken wrappers)~~
~~Wire up IPC handlers for all services (config, crypt, display, help, i18n, workspace)~~
~~Complete display menu handlers (New/List workspace)~~
~~Tray icon setup with asset embedding~~
~~Test coverage for io packages~~
System tray brand-specific menus

Phase 2: Multi-Brand Support

Define brand configuration system (config? build flags?)
Implement brand-specific tray menus (AdminHub, ServerHub, GatewayHub, DeveloperHub, ClientHub)
Brand-specific theming/assets
Per-brand default workspace configurations

Phase 3: Remote Storage

Complete SFTP backend (pkg/io/sftp/)
Complete WebDAV backend (pkg/io/webdav/)
Workspace sync across storage backends
Conflict resolution for multi-device access

Phase 4: Enhanced Crypto

Key management UI (import/export, key rotation)
Multi-recipient encryption
Hardware key support (YubiKey, etc.)
Encrypted workspace backup/restore

Phase 5: Developer Experience

TypeScript types for IPC messages (codegen from Go structs)
Hot-reload for service registration
Plugin system for third-party services
CLI tooling for workspace management

Phase 6: Distribution

Auto-update mechanism
Platform installers (DMG, MSI, AppImage)
Signing and notarization
Crash reporting integration

Getting Help

User Guide: Detailed usage and concepts.
FAQ: Frequently asked questions.
Workflows: Common task sequences.
Troubleshooting: Solving common issues.
Configuration: Config file reference.

# Check environment
core doctor

# Command help
core <command> --help

For New Contributors

Run task test to verify all tests pass
Follow TDD: task test-gen creates stubs, implement to pass
The dual-constructor pattern is intentional: New(deps) for tests, Register() for runtime
IPC handlers in each service's HandleIPCEvents() are the frontend bridge

Name		Name	Last commit message	Last commit date
Latest commit History 973 Commits
.claude		.claude
.core		.core
.githooks		.githooks
docs		docs
pkg/core		pkg/core
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
LICENSE.txt		LICENSE.txt
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

Core

Vision

CLI Quick Start

Framework Quick Start (Go)

Prerequisites

Development Workflow (TDD)

Building & Running

Configuration

Configuration File

Format

Environment Variables

Layered Configuration Mapping

Common Environment Variables

All Tasks

Architecture

Project Structure

Service Pattern (Dual-Constructor DI)

IPC/Action System

Wails v3 Frontend Bindings

How It Works

Current Binding Architecture

Configuration Management

Project and Service Configuration Files

Format

The IPC Bridge Pattern (Chosen Architecture)

Generating Bindings

Service Interfaces (pkg/framework/core/interfaces.go)

Current State (Prototype)

Working

Package Deep Dives

pkg/crypt

pkg/io - Storage Abstraction

Future Work

Phase 1: Core Stability

Phase 2: Multi-Brand Support

Phase 3: Remote Storage

Phase 4: Enhanced Crypto

Phase 5: Developer Experience

Phase 6: Distribution

Getting Help

For New Contributors

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Service Interfaces (`pkg/framework/core/interfaces.go`)

Packages