From 1a92d3c173d88e59a8d9c6779c967141096fcf6a Mon Sep 17 00:00:00 2001 From: Thomas Schubart <24721048+Furisto@users.noreply.github.com> Date: Mon, 24 Nov 2025 21:15:04 +0100 Subject: [PATCH 1/6] Update readme --- README.md | 70 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 48 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 69e873c..ab8e299 100644 --- a/README.md +++ b/README.md @@ -7,21 +7,19 @@

- API-first • Superior tool calling • Multi-agent workflows • Complete transparency + API-first • CodeMode tool calling • Multi-agent workflows • Self-hostable

--- ## Why Construct? -Most AI coding tools are black boxes. You interact through a web interface or thin CLI wrapper, with limited visibility and minimal control over the system. +Most AI coding tools lock you into their interface and workflows. Construct is built for integration and automation. Construct gives you full programmatic control. -Construct is different: - -- **Full transparency**: See every tool call, export all data, understand costs - **Programmatic control**: Script every operation, integrate with existing workflows - **Extensibility**: Build custom agents, access everything via API - **Vendor independence**: Self-host, switch models, no lock-in +- **Full visibility**: Export all data, track costs, inspect every operation ## Overview @@ -77,20 +75,26 @@ See [Tool Calling in Construct](docs/tool_calling.md) for a detailed technical a The CLI is just one client. The daemon exposes every operation via ConnectRPC. -**Example:** Trigger code reviews from CI: +Build your own IDE plugins, Slack bots, or automation scripts. Full programmatic control over agents, tasks, messages, models, and providers. + +#### Agent-as-a-Service (Coming Soon) -```python -from construct import Client +Construct's daemon can run anywhere - locally, on a remote server, or in cloud sandboxes. The architecture supports connecting to remote daemons, enabling: -client = Client() -task = client.tasks.create(agent="reviewer", workspace=".") -result = client.messages.create( - task_id=task.id, - content="Review this PR for security issues" -) +**Deploy daemon to cloud sandbox:** +```bash +# Run daemon in isolated environment (Docker, E2B, Fly.io, etc.) +construct daemon run --listen-http 0.0.0.0:8080 ``` -Build your own IDE plugins, Slack bots, or automation scripts. Full programmatic control over agents, tasks, messages, models, and providers. +**Use cases enabled by remote daemon support:** +- **Isolated execution**: Run agents in sandboxed environments separate from your development machine +- **Persistent agents**: Long-running tasks that continue even when you disconnect +- **Multi-client control**: Multiple CLI instances can interact with the same daemon +- **Cloud integration**: Deploy on serverless platforms, Kubernetes, or container services +- **HTTP/2 streaming**: Real-time updates via ConnectRPC for interruptible agent runs + +Unlike AI tools designed only for local use, Construct's API-first design makes it a natural fit for remote agent orchestration. Remote context switching and management commands coming soon. Language SDKs for Python, TypeScript, and Go coming soon. @@ -128,16 +132,33 @@ construct agent create reviewer \ ## Architecture -Construct is built with a modular architecture that separates concerns between: +Construct follows a daemon-based, client-server architecture designed for extensibility and programmatic access: + +```mermaid +graph TD + CLI[CLI Client] -->|HTTP/2| API[API Layer
ConnectRPC] + Custom[Custom Clients] -.->|HTTP/2| API + API --> TR[Task Reconciler] + TR --> INT[CodeAct Interpreter
Sobek VM] + TR --> Provider[Model Providers
Anthropic/OpenAI/etc] + TR --> DB[(SQLite Database)] + INT --> Tools[Tool Execution
read_file, edit_file, grep, etc] +``` -- **Backend**: Handles agent runtime, model providers, and tool execution -- **API Layer**: Provides a consistent interface for all operations -- **Frontend CLI**: Offers an intuitive terminal interface for interacting with the system +**Key components:** +- **Daemon**: Background service managing agent execution, state, and coordination +- **ConnectRPC API**: HTTP/2-based RPC exposing all operations via Protocol Buffers +- **Task Reconciler**: Orchestrates conversation flows between models and tool execution +- **CodeAct Interpreter**: Executes JavaScript-based tool calls in sandboxed environment +- **Storage**: SQLite database for persisting all state -The multi-agent system allows for specialized agents to collaborate on tasks, with the runtime managing message passing and coordination between agents. +See [Architecture Documentation](docs/architecture.md) for detailed technical deep dive. ## Quick Start +> [!WARNING] +> Construct is in preview. Expect bugs and missing features as we actively develop toward a stable release. [Report issues](https://github.com/furisto/construct/issues) to help us improve. + ### Installation ```bash @@ -281,8 +302,13 @@ Construct is actively developed. Planned features: - **More providers** - Bedrock, Gemini, and additional model providers - **Agent delegation** - Agents can send messages to and delegate work to other agents - **Fine-grained permissions** - Control which tools each agent can use -- **Complete privacy mode** - No analytics, no telemetry +- **Complete privacy mode** - Use local models, no analytics, no telemetry - **Language SDKs** - Python, TypeScript, and Go client libraries +- **Checkpoints** - Create snapshots of the repository state before agent modifications +- **Long Horizon tasks** - Support for complex, multi-step tasks +- **Agent.MD support** - Integration with Agent.MD specification for standardized agent configuration and behavior +- **Sandboxing** - Isolate agents in secure containers +- **Virtual Agents** - Agents that adapt their behavior and capabilities based on the model they're using See [GitHub Issues](https://github.com/furisto/construct/issues) for detailed feature requests and progress tracking. @@ -325,4 +351,4 @@ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for det This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details. -Copyright 2025 Thomas Schubart +Copyright 2025 Thomas Schubart \ No newline at end of file From 681f09ed3e1f374c5b4912cdaba9591137700a5e Mon Sep 17 00:00:00 2001 From: Thomas Schubart <24721048+Furisto@users.noreply.github.com> Date: Mon, 24 Nov 2025 21:19:33 +0100 Subject: [PATCH 2/6] Roadmap --- README.md | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index ab8e299..34b7eb3 100644 --- a/README.md +++ b/README.md @@ -296,19 +296,26 @@ construct config get cmd.new.agent ## Roadmap -Construct is actively developed. Planned features: +Construct is under active development. Planned features grouped by category: +**Integration & APIs** +- **Language SDKs** - Python, TypeScript, and Go client libraries +- **Remote daemon support** - CLI commands for managing and switching between remote contexts - **MCP support** - Model Context Protocol integration + +**Model Providers** - **More providers** - Bedrock, Gemini, and additional model providers -- **Agent delegation** - Agents can send messages to and delegate work to other agents -- **Fine-grained permissions** - Control which tools each agent can use -- **Complete privacy mode** - Use local models, no analytics, no telemetry -- **Language SDKs** - Python, TypeScript, and Go client libraries -- **Checkpoints** - Create snapshots of the repository state before agent modifications -- **Long Horizon tasks** - Support for complex, multi-step tasks -- **Agent.MD support** - Integration with Agent.MD specification for standardized agent configuration and behavior -- **Sandboxing** - Isolate agents in secure containers -- **Virtual Agents** - Agents that adapt their behavior and capabilities based on the model they're using +- **Complete privacy mode** - Use local models with zero telemetry + +**Agent Capabilities** +- **Agent delegation** - Agents can collaborate and delegate work to specialized agents +- **Virtual agents** - Agents that adapt behavior based on the model they use +- **Long-horizon tasks** - Enhanced support for complex, multi-day tasks + +**Security & Safety** +- **Fine-grained permissions** - Control which tools each agent can access +- **Sandboxing** - Isolate agent execution in secure containers +- **Checkpoints** - Create snapshots of repository state before agent modifications See [GitHub Issues](https://github.com/furisto/construct/issues) for detailed feature requests and progress tracking. From e42770ee594c1ca33102579c51b2ae96e398640f Mon Sep 17 00:00:00 2001 From: Thomas Schubart <24721048+Furisto@users.noreply.github.com> Date: Mon, 24 Nov 2025 21:24:08 +0100 Subject: [PATCH 3/6] Examples --- README.md | 41 ++++++++++------------------------------- 1 file changed, 10 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 34b7eb3..d64ad78 100644 --- a/README.md +++ b/README.md @@ -171,7 +171,7 @@ go build -o construct sudo mv construct /usr/local/bin/ ``` -### Setup (5 minutes) +### Setup ```bash # 1. Install daemon @@ -209,13 +209,13 @@ construct new --agent edit ```bash # Start a new interactive session -construct new --agent coder +construct new --agent plan # Resume a previous conversation construct resume --last # Work in a specific directory -construct new --agent coder --workspace /path/to/project +construct new --agent edit --workspace /path/to/project ``` ### Non-Interactive Mode @@ -253,45 +253,24 @@ construct agent create "reviewer" \ --model "claude-3-5-sonnet" # Edit agent configuration -construct agent edit coder +construct agent edit reviewer # Get agent details -construct agent get coder --output json +construct agent get reviewer --output json ``` -### Task and Message Management +### Task Management & Configuration ```bash -# Create a new task -construct task create --agent coder --workspace /project - -# List recent tasks +# List and manage tasks construct task list --agent coder - -# View task details construct task get -# List messages in a conversation -construct message list --task - -# View specific message -construct message get --output yaml -``` - -### Configuration +# Export conversation history +construct message list --task -o json -```bash -# Set default agent for new conversations +# Configure defaults construct config set cmd.new.agent "coder" - -# Set default output format -construct config set output.format "json" - -# Configure max turns for ask command -construct config set cmd.ask.max-turns 10 - -# View current configuration -construct config get cmd.new.agent ``` ## Roadmap From a5e3711b28593e7d8404e2f1007b1d0b3b6f633c Mon Sep 17 00:00:00 2001 From: Thomas Schubart <24721048+Furisto@users.noreply.github.com> Date: Mon, 24 Nov 2025 23:20:24 +0100 Subject: [PATCH 4/6] Installation --- README.md | 34 +++++++++++++--------------------- 1 file changed, 13 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index d64ad78..6e17e86 100644 --- a/README.md +++ b/README.md @@ -67,9 +67,9 @@ for (const file of routeFiles.files) { } ``` -One execution instead of dozens of separate tool calls. Research shows this approach achieves 20% higher success rates vs JSON tool calling. +One execution instead of dozens of separate tool calls. Research by Wang et al. (2024) demonstrates that code-based tool calling achieves up to 20% higher success rates compared to JSON and text-based approaches across 17 different language models. -See [Tool Calling in Construct](docs/tool_calling.md) for a detailed technical analysis. +See [Tool Calling in Construct](docs/tool_calling.md) for a detailed technical analysis and full citation. ### API-First Architecture @@ -161,8 +161,18 @@ See [Architecture Documentation](docs/architecture.md) for detailed technical de ### Installation +**macOS (Homebrew):** +```bash +brew tap furisto/tap +brew install construct +``` + +**Download pre-built binary:** + +Download the latest release for your platform from [GitHub Releases](https://github.com/furisto/construct/releases). + +**Build from source:** ```bash -# Clone and build git clone https://github.com/furisto/construct cd construct/frontend/cli go build -o construct @@ -181,24 +191,6 @@ construct daemon install export ANTHROPIC_API_KEY="sk-ant-..." construct modelprovider create anthropic --type anthropic -# 3. Register models -construct model create claude-sonnet-4 \ - --provider anthropic \ - --context-window 200000 - -construct model create claude-haiku-3.5 \ - --provider anthropic \ - --context-window 200000 - -# 4. Create agents -construct agent create edit \ - --model claude-sonnet-4 \ - --prompt "You are a coding assistant who writes clean, well-documented code" - -construct agent create quick \ - --model claude-haiku-3.5 \ - --prompt "You are a fast coding assistant for quick tasks" - # 5. Start coding construct new --agent edit ``` From 7382f1fe97cee8d2cf3032abb25871bcd546babc Mon Sep 17 00:00:00 2001 From: Thomas Schubart <24721048+Furisto@users.noreply.github.com> Date: Mon, 24 Nov 2025 23:24:35 +0100 Subject: [PATCH 5/6] Links --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6e17e86..8a3f282 100644 --- a/README.md +++ b/README.md @@ -291,7 +291,7 @@ Construct is under active development. Planned features grouped by category: See [GitHub Issues](https://github.com/furisto/construct/issues) for detailed feature requests and progress tracking. ## Documentation - +- [Architecture Documentation](docs/architecture.md) - Detailed technical deep dive into Construct's design - [Tool Calling in Construct](docs/tool_calling.md) - Technical deep dive on JavaScript-based tool calling - [CLI Reference](docs/cli_reference.md) - Complete reference for all CLI commands - [API Reference](https://docs.construct.sh/api) (Coming soon) From 2730a4c149cb572291bf9f305490cf6d6362e171 Mon Sep 17 00:00:00 2001 From: Thomas Schubart <24721048+Furisto@users.noreply.github.com> Date: Mon, 24 Nov 2025 23:51:27 +0100 Subject: [PATCH 6/6] Fix numbers --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8a3f282..65ca68a 100644 --- a/README.md +++ b/README.md @@ -191,7 +191,7 @@ construct daemon install export ANTHROPIC_API_KEY="sk-ant-..." construct modelprovider create anthropic --type anthropic -# 5. Start coding +# 3. Start coding construct new --agent edit ```