{"id":14990,"library":"tycono","title":"Tycono AI Company Builder","description":"Tycono is an open-source, local-first framework for building and orchestrating multi-agent AI organizations, conceptualized as 'Company-as-Code'. It allows users to define AI agents, roles, and company hierarchies using declarative YAML and Markdown configurations, then watch them autonomously plan, execute, and learn from complex tasks. The system features a terminal-native user interface (TUI) for real-time supervision and manages persistent knowledge across sessions. The client library, `tycono`, is currently at version 0.3.44 and is under active development with frequent minor releases. Its companion, `tycono-server`, reached its first production-ready stable release at v0.1.0, providing a headless API backend. Key differentiators include its cost-efficiency features like 'Auto-Amend' for reducing LLM usage, and its ability to simulate and run entire AI companies for autonomous research and development.","status":"active","version":"0.3.44","language":"javascript","source_language":"en","source_url":"https://github.com/seongsu-kang/tycono","tags":["javascript","ai","tycono","company","organization","roles","claude","agent","multi-agent"],"install":[{"cmd":"npm install tycono","lang":"bash","label":"npm"},{"cmd":"yarn add tycono","lang":"bash","label":"yarn"},{"cmd":"pnpm add tycono","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for running the headless API backend that orchestrates multi-agent operations. While 'tycono' handles configuration, 'tycono-server' executes the AI company logic.","package":"tycono-server","optional":true},{"reason":"Direct integration with Claude for LLM capabilities, often via a plugin. Requires an API key for operation.","package":"anthropic","optional":false}],"imports":[{"note":"Primary entry point for the interactive Terminal User Interface (TUI). Often invoked via `npx tycono`.","symbol":"runTyconoTUI","correct":"import { runTyconoTUI } from 'tycono/cli';"},{"note":"For programmatic definition of an AI company structure (roles, agents, hierarchy). Assumes an SDK exists for this, as 'Company-as-Code' is usually file-based (YAML/Markdown).","wrong":"const defineCompany = require('tycono').defineCompany;","symbol":"defineCompany","correct":"import { defineCompany } from 'tycono/config';"},{"note":"To programmatically initiate a task for an AI company. This likely interacts with the 'tycono-server' API.","wrong":"const executeTask = require('tycono').executeTask;","symbol":"executeTask","correct":"import { executeTask } from 'tycono/api';"}],"quickstart":{"code":"import { defineCompany, executeTask } from 'tycono/api';\nimport { HumanAgent, ClaudeAgent, Role } from 'tycono/agents'; // Assuming agent types\n\nconst ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY ?? '';\n\nif (!ANTHROPIC_API_KEY) {\n  console.error('ANTHROPIC_API_KEY environment variable not set.');\n  process.exit(1);\n}\n\n// Define roles within the company\nconst ceoRole = new Role('CEO', 'Oversees overall company strategy and delegates tasks.');\nconst engineerRole = new Role('Engineer', 'Implements technical solutions and writes code.');\nconst qaRole = new Role('QA', 'Tests and validates implemented solutions.');\n\n// Define agents and assign them roles\nconst ceoAgent = new ClaudeAgent('Alice', 'claude-3-opus-20240229', ceoRole, ANTHROPIC_API_KEY);\nconst engineerAgent = new ClaudeAgent('Bob', 'claude-3-sonnet-20240229', engineerRole, ANTHROPIC_API_KEY);\nconst qaAgent = new ClaudeAgent('Charlie', 'claude-3-haiku-20240229', qaRole, ANTHROPIC_API_KEY);\n\n// Define the company structure\nconst myAICorp = defineCompany({\n  name: 'Innovation Inc.',\n  description: 'An AI company focused on rapid prototyping and development.',\n  roles: [ceoRole, engineerRole, qaRole],\n  agents: [ceoAgent, engineerAgent, qaAgent],\n  reportingStructure: [\n    { from: engineerAgent, to: ceoAgent }, // Engineer reports to CEO\n    { from: qaAgent, to: ceoAgent }      // QA reports to CEO\n  ] // Simplified reporting for example\n});\n\nasync function runAICompanyTask() {\n  console.log(`Starting task for ${myAICorp.name}...`);\n  try {\n    const result = await executeTask(myAICorp, 'Develop a simple web-based calculator application.', {\n      // Optional parameters for task execution, e.g., output directory, max steps\n      outputDirectory: './projects/calculator-app',\n      verbose: true\n    });\n    console.log('Task completed. Final output:', result.finalReport);\n  } catch (error) {\n    console.error('Error executing task:', error);\n  }\n}\n\nrunAICompanyTask();","lang":"typescript","description":"This quickstart demonstrates how to programmatically define an AI company with distinct roles and agents using assumed Tycono SDK APIs. It then initiates an autonomous task for the company, showcasing how to leverage LLMs (specifically Claude) for multi-agent collaboration. This example assumes 'tycono-server' is running to orchestrate the agents and requires an Anthropic API key."},"warnings":[{"fix":"Review the latest documentation or `npx tycono` TUI for updated interaction patterns. Update any custom scripts or integrations to align with the new 'Multi-Wave' and 'Dual Mode' concepts.","message":"Version 0.2.0 introduced significant changes to the core interaction model, making the TUI the default interface and adding 'Multi-Wave Resume' and 'Dual Mode' functionalities. Older CLI commands or programmatic integrations expecting pre-0.2.0 behavior may break.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Examine the changelog between v0.2.0 and v0.3.10 for specifics. Migrate any custom code from 'Job'-centric paradigms to the new 'Session'-centric approach.","message":"The internal session management was refactored with a 'Session-Centric migration', explicitly removing 'Job' from the core. This indicates a potential breaking change for any programmatic interfaces or configurations that directly referenced 'Job' entities.","severity":"breaking","affected_versions":">=0.3.10"},{"fix":"Ensure `tycono-server` (available as a separate npm package) is installed and running, and that necessary LLM API keys (e.g., `ANTHROPIC_API_KEY`) are correctly set in your environment.","message":"Tycono relies heavily on an LLM provider (e.g., Anthropic Claude) and the `tycono-server` backend for full functionality. Users might configure the `tycono` client without realizing the separate server component and API keys are critical for execution.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Thoroughly validate your YAML/Markdown configuration files against the schema or examples provided in the official documentation. Use linters or schema validators if available.","message":"The 'Company-as-Code' approach uses YAML and Markdown files for defining agents and organizational structure. Incorrect formatting, missing required fields, or logical errors in these declarative files can lead to unexpected agent behavior or runtime errors.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Start the `tycono-server` in a separate terminal (`npm install -g tycono-server && tycono-server start`) or ensure the `TYCONO_SERVER_URL` environment variable points to the correct address if it's not local.","cause":"The 'tycono' client cannot connect to the 'tycono-server' instance.","error":"Error: Tycono server not running or unreachable at http://localhost:PORT"},{"fix":"Set the `ANTHROPIC_API_KEY` environment variable with your valid Anthropic API key before running Tycono. For other LLMs, consult the specific documentation.","cause":"The LLM (e.g., Claude) API key is not provided, preventing agents from functioning.","error":"Error: Missing required environment variable ANTHROPIC_API_KEY"},{"fix":"Inspect your agent/role configuration files for syntax errors or missing mandatory properties. Ensure all required fields, such as `id`, `name`, `level`, `model`, etc., are present and correctly formatted.","cause":"A YAML or Markdown agent/role definition file is malformed or missing a critical field like 'name'.","error":"TypeError: Cannot read properties of undefined (reading 'name') in agent configuration."},{"fix":"Use a modern terminal emulator (e.g., iTerm2, Kitty, Alacritty, VS Code integrated terminal) that supports 256 colors. Ensure your `TERM` environment variable is correctly set (e.g., `xterm-256color`).","cause":"The terminal environment does not meet the minimum requirements for the rich TUI experience.","error":"Error: The Tycono TUI requires a terminal that supports 256 colors."}],"ecosystem":"npm"}