Lumecode: A Privacy-First Multi-Agent AI Coding Assistant with Terminal-Based Interface

International Research Journal of Engineering and Technology (IRJET) e-ISSN: 2395-0056

Volume: 13 Issue: 03 | Mar 2026 www.irjet.net p-ISSN: 2395-0072

Lumecode: A Privacy-First Multi-Agent AI Coding Assistant with Terminal-Based Interface

K Vishweshwar Rao 1, K Moulika2, K Akshitha3, K Sanjay Kumar4, K Praveen Kumar5

1,2,3,4UG Students, Department of Computer Science and Engineering, Joginpally B.R. Engineering College, Hyderabad, India

5Assistant Professor, Department of Computer Science and Engineering, Joginpally B.R. Engineering College, Hyderabad, India

Abstract - The rapid adoption of Large Language Models (LLMs) in software development has produced powerful AI coding assistants; however, most existing solutions are cloud-dependent, cost-prohibitive, privacy-invasive, or require disruptive context switching between browser and development environment. This paper presents Lumecode, an open-source, privacy-first, multi-agent AI coding assistant that operates natively in the terminal. Lumecode addresses these limitations through four design pillars: (i) a multi-provider LLM backend supporting Google Gemini, Groq, OpenRouter, and Ollama defaulting to free-tier services; (ii) a specialized multi-agent system comprising Build, Plan, Review, and General agents with fine-grained capabilitypermissions;(iii)a React/Ink-basedterminaluser interface keeping developers in their natural workflow; and (iv) a SQLite-backed persistent session system. Evaluation demonstrates sub-second startup latency (380ms), 85% autonomous task completion with the Build agent, and zero API cost across 200 test interactions using free-tier providers.

Key Words: Terminal UI, AI Coding Assistant, MultiAgent System, LLM, Privacy-First, Function Calling, Open-Source, MCP, Session Persistence, React/Ink

1. INTRODUCTION

Artificial Intelligence (AI) coding assistants have become central productivity tools for software developers, with studies demonstrating measurable gains in development speed [1]. However, widespread adoption is constrained bythreestructuralbarriers:cost(enterprisesubscriptions typically exceed $20/month per developer), privacy (source code is transmitted to cloud providers), and workflow disruption (most tools operate in browser or IDE contexts, requiring developers to leave their primary workingenvironment,theterminal).

Terminal-resident developers working in remote environments, embedded systems, DevOps pipelines, or resource-constrained machines are underserved by existing solutions. Command-line tools such as Aider [2] and Shell-GPT [5] have addressed parts of this gap but typically require paid API keys, lack multi-agent specialization, or offer limited TUI richness. No existing

open-source terminal tool combines a rich interactive interface, multiple specialized agents, free-tier-first providers, and persistent session management in a single system.

This paper introduces Lumecode, an open-source AI coding agent designed specifically for terminal environments. The key contributions are: (i) a provideragnosticLLMbackendwithautomaticfallbackacrossfour providers defaulting to free-tier APIs; (ii) a multi-agent architecture with a formal permission matrix governing filesystemaccessandcommandexecutionperagentrole; (iii) a React/Ink-based terminal user interface offering keyboard-driven visual interaction; (iv) a persistent SQLite-backed session store; and (v) integration with the Model Context Protocol (MCP) and Language Server Protocol(LSP)forextensibletoolconnectivity.

1.1 Problem Statement

Most AI coding tools transmit source code to cloud servers, incur recurring subscription costs, and require switching between terminal and browser environments. Developers working in terminal-centric workflows such as remote servers, embedded systems, or DevOps pipelines lack a privacy-preserving, cost-free, feature-rich AI assistant that integrates seamlessly into theirexistingenvironmentwithoutworkflowdisruption.

1.2 Proposed System

Lumecode is proposed as an open-source, terminal-native multi-agent AI coding assistant that supports free-tier and fully-local LLM providers. The system integrates four specialized agents (Build, Plan, Review, General) with a formal permission security framework, a React/Ink terminal UI, SQLite session persistence, and MCP/LSP protocol support. Lumecode achieves zero API cost through free-tier provider defaults while maintaining full privacy through optional Ollama localinference

Volume: 13 Issue: 03 | Mar 2026 www.irjet.net p-ISSN: 2395-0072

2. RELATED WORK

2.1 IDE-Integrated Assistants

GitHub Copilot [1] and Amazon CodeWhisperer [4] operate as IDE plugins providing inline code suggestionsusingfine-tunedLLMs.Thesetoolsaretightly coupled to specific IDEs and transmit code to proprietary cloud backends. Cursor extends this model with full-file context and multi-turn conversation but remains a modified desktop IDE rather than a terminal tool. None nativelysupportlocalinference,limitingtheirapplicability inprivacy-sensitiveorofflinedevelopmentscenarios.

2.2 Terminal-Based Tools

Aider [2] is the closest comparable terminal tool, supporting multi-file editing via git-backed conversation. However, Aider requires paid API keys by default and provides a plain readline interface without a rich TUI. Shell-GPT [5] provides LLM-powered terminal assistance but is a single-shot query tool without agentic multi-turn capability. Continue [3] operates as a VS Code extension that can invoke local models but remains IDE-bound and notusablefromapureterminalenvironment.

2.3

Multi-Agent Frameworks

AutoGen [6] and CrewAI enable multi-agent orchestration but are designed for workflow automation rather than interactive developer assistance. They lack terminal UIs and persistent session storage appropriate for development use. Lumecode occupies the intersection of rich TUI, multi-agent specialization, free-tier operation, and privacy-first design a combination not previously addressedintheliterature.

3. SYSTEM ARCHITECTURE

Lumecode is organized into five hierarchical layers following a layered pattern with clean interface boundaries, enabling independent extensibility of each subsystem. The architecture employs established design patterns to maintain separation of concerns across all components. Figure 1 illustrates the complete four-tier multi-agentarchitectureoftheLumecodesystem.

Fig -1: Lumecode4-TierMulti-AgentAIArchitectureand Multi-ProviderLLMIntegration

Figure1showsthefour-tierarchitectureoftheLumecode systemconsistingofthePresentationLayer,Orchestration Layer,Agent Layer,and LLMProviderLayer. The Request Router and Agent Orchestrator manage task routing between specialized agents such as Planner, Code, Debug, and General agents. The system integrates multiple LLM providersthroughaproviderroutingmechanismanduses persistentstorageforsessiondata,logs,andcaching.

Fig -2: AgentOrchestrationWorkflow

Figure2illustratestheworkflowoftheLumecodesystem. The user request is received by the Request Router, and the task is classified and forwarded to the appropriate agent. The agent processes the task using an LLM provider,and theresponse isformatted, stored in session logs,andreturnedtotheuser.

International Research Journal of Engineering and Technology (IRJET) e-ISSN: 2395-0056

Volume: 13 Issue: 03 | Mar 2026 www.irjet.net p-ISSN: 2395-0072

Table -1: LumecodeArchitecturalPatternsand Components

Pattern Applied In

Singleton ConfigManager,SessionManager, ProviderRegistry,AgentRegistry, ToolRegistry

Factory createProvider(),createAgent(), createMCPClient()

Strategy BaseProvidertoGemini,Groq,OpenRouter, Ollamaadapters

Observer Healthmonitorevents,MCPserver notifications

Adapter MCPtoolstoLumecodetools;LSPresponses tocodeintelligence

Template Method

BaseProvider,BaseAgent,BaseToolabstract classes

Table 1 summarizes the software design patterns used in theLumecodesystem.PatternssuchasSingleton,Factory, Strategy, Observer, Adapter, and Template Method are used to implement configuration management, provider integration, agent creation, monitoring, and tool integration.

3.1 Architectural Layers

The CLI/TUI Layer accepts user input through Commander-based commands and renders the React/Ink terminal interface. It translates keyboard events, slash commands, and interactive selections into structured requests for the Engine layer. The Engine Layer is the central orchestration component managing the active agent and provider, the agentic tool-use loop, and session persistence. The Agent System and Provider System operate as parallel subsystems: agents encapsulate behavioral specialization while providers encapsulate API communication specifics. The Strategy pattern decouples these concerns, allowing any agent to be paired with any provider without code changes. The Infrastructure Layer comprisescross-cuttingservices:theSQLitesessionstore, security and permissions manager, git integration, MCP client,andLSPclient.

4. IMPLEMENTATION

4.1 Multi-Provider LLM Integration

The provider subsystem defines an abstract BaseProvider class requiring four operations: chat() for synchronouscompletion,chatStream()forreal-timetoken delivery, isAvailable() for health-checking, and listModels() for dynamic model enumeration. The ProviderRegistry implements an automatic fallback chain

evaluated at startup via asynchronous isAvailable() probes. Table 2 presents the supported providers and theircapabilities.

Table -2: SupportedLLMProvidersandCapabilities

Provider Free Tier Context (tokens) Strea ming Function Calling

Google Gemini 60 RPM 1,000,000 Yes Yes

Groq 30 RPM 32,768 Yes Yes

OpenRouter Free models Modeldep. Yes Yes

Ollama (Local) Unlimit ed Modeldep. Yes Model-dep.

Table 2 compares the supported LLM providers based on freetieravailability,contextsize,streamingcapability,and function calling support. This comparison helps in selecting providers for fallback, performance, and cost optimization.

4.2 Multi-Agent System

Four specialized agents are implemented, each extending BaseAgent and overriding initializeTools() to registeronlythetoolsappropriatetotheirrole.TheBuild agent has full file system read/write, terminal execution, and network access. The Plan agent has read-only file access and execution with confirmation prompts. The Review agent has read-only access exclusively. The General agent has full access with confirmation on destructive actions. Agent system prompts are stored as externalizedMarkdownfilesloadedatruntime,withagent configuration expressed in YAML specifying maximum contexttokens,temperature,retrylimits,andenabledtool categoriesperagent.

4.3 Tool Execution Framework

Each tool extends BaseTool and declares its JSON Schema parameter definition. The ToolRegistry automaticallyserializesthesedefinitionstoeitherOpenAIcompatible or Gemini-compatible function definition formats at request time, enabling provider-agnostic tool invocation. Six built-in tools are provided: file_read (with optional line range parameters), file_write (atomic create or overwrite), file_edit (targeted section editing), directory_list, terminal_execute, and search_files (regex patternmatching).Theengineimplementsanagentictooluse loop using the OpenAI tool-calling protocol, terminating when the LLM produces a stop finish reason ortheconfigurableiterationlimitisreached.

Volume: 13 Issue: 03 | Mar 2026 www.irjet.net p-ISSN: 2395-0072

4.4 Session Persistence

Session data is stored in a SQLite database at ~/.lumecode/lumecode.db using Bun's native bun:sqlite bindings. The schema comprises two tables: sessions (metadata:agent,provider,model,workingdirectory)and messages (full conversation history: role, content, timestamp), with a foreign key cascade ensuring referential integrity. The SessionManager exposes CRUD operations and full-text search over message content, enablingcross-invocationconversationcontinuity.

4.5 Security and Permission System

Each agent role is associated with a PermissionRuleset specifying allowed and denied path patternsforfileoperationsusingglobsyntax,allowedand deniedshellcommandpatterns,networkaccessflags,and a requiresConfirmation boolean. Critical paths (.git/**, .env*, node_modules/**) are denied for write operations across all agents. The rate limiter module enforcesper-providerrequestlimitstopreventaccidental quotaexhaustion.

4.6 Terminal User Interface

The TUI is implemented using React 18 with the Ink rendering engine, which maps React component trees to terminal escape codes. The interface presents a status bar (model, token count, cost), scrollable message history with role-distinguished borders, syntax-highlighted code blocks, command history navigation, and an agent/model selectorrow.Figure2showstheLumecodemaininterface and Figure 3 shows the keyboard shortcuts reference panel.

flash-exp:free model. The status bar displays the active agent (BUILD), provider (openrouter), token count (0/128.0k), and cost ($0.0000). The central panel shows the LUMECODE ASCII logo with the tagline "AI-powered codingthat'sprivate, open, andbeautiful" anda tip panel. The input field at the bottom accepts natural language codingrequests.

Fig -4: LumecodeKeyboardShortcutsandCommands ReferencePanel

Figure 4 shows the Lumecode help overlay displaying all keyboardshortcuts,slashcommands,andtoolcommands. ShortcutsincludeCtrl+C(Exit),Tab(Switchagent),Ctrl+P (Switch provider), Ctrl+O (Switch model), Ctrl+N (New session),andCtrl+L(Clearconversation).Slashcommands include /help, /quit, /clear, /agent, /provider, /model, /models, and /status. Tool commands include /tools, /ls, /cat, /search, and /run for file system and terminal operations.

5. RESULTS AND DISCUSSION

5.1 Startup Performance

Cold-start latency from shell invocation to first interactivepromptwasmeasuredat380ms+/-42msona standard developer workstation (Intel Core i7, 16GB RAM). This is attributed to Bun's ahead-of-time compilation model and avoidance of Node.js's slower module resolution. Provider availability probing is performed asynchronously and does not block the initial prompt display, ensuring immediate user interaction readiness.

5.2 Agentic Task Completion

Figure 3 shows the Lumecode main terminal interface running the BUILD agent with the openrouter:gemini-2.0-

A set of 20 representative developer tasks was used to evaluate the Build agent including file creation from natural language description, multi-file refactoring, dependency installation via terminal execution, git

Volume: 13 Issue: 03 | Mar 2026 www.irjet.net

operations, and code review with inline suggestions. The Buildagentsuccessfullycompleted17of20taskswithout user intervention, yielding an 85% autonomous completionrate.Allthreefailuresinvolvedtasksrequiring real-time web lookups not addressable with the built-in tool set. No unauthorized file accesses were observed acrossalltestruns.

5.3 Cost and Privacy Analysis

Over 200 test interactions using the Gemini freetier provider, total API cost was $0.00. All interactions routed to Ollama remained fully local with no external network traffic generated. Table 3 presents a comprehensive feature comparison against existing terminal-basedAItools.

Table -3: FeatureComparisonwithExistingTerminalBasedAITools

Localmodel(Ollama)

Multi-agentroles 4 agents

RichTUI(React/Ink) Yes Minimal None IDEonly

Sessionpersistence SQLite Git-based No Yes MCPintegration

Table 3 confirms that Lumecode is the only terminalbased AI tool combining free-tier native support, local model inference, multi-agent specialization, a rich TUI, SQLitesessionpersistence,MCPintegration,andper-agent securitypermissionsinasinglesystem.

6. CONCLUSIONS AND FUTURE WORK

ThispaperpresentedLumecode,anopen-source,privacyfirst, multi-agent AI coding assistant for terminal environments. The system demonstrates that feature parity with commercial AI development tools can be achieved at zero cost through free-tier provider selection, while maintaining superior privacy through local model support and transparent permission controls. The multiagent architecture provides a practical model for specializing LLM behavior without requiring separate deployments, supporting four distinct operational modes throughconfigurablepermissionrulesets.

Futureworkwillpursue:(i)aGo-basedTUIrewriteusing Bubbletea/Lipgloss for improved rendering performance and single-binary distribution; (ii) context compaction algorithms for extended sessions within fixed context

window limits; (iii) integration with additional MCP servers to expand the tool ecosystem; (iv) a plugin architecture allowing community-contributed agents and tools; and (v) formal evaluation against standardized software engineering benchmarks such as SWE-bench [10]. Lumecode is available at https://github.com/anonymus-netizien/Lumecode under theMITLicense.

REFERENCES

[1] GitHub,"GitHubCopilot:YourAIpairprogrammer,"GitHub, Inc., 2024. [Online]. Available: https://github.com/features/copilot

[2] P. Gauthier, "Aider: AI pair programming in your terminal," 2024.[Online].Available:https://aider.chat

[3] Continue Dev, "Continue: Open-source autopilot for software development," 2024. [Online]. Available: https://continue.dev

[4] Amazon Web Services, "Amazon CodeWhisperer: AIpoweredcodingcompanion,"AWS,2024.

[5] T. Farber, "ShellGPT: A command-line productivity tool poweredbyAI,"GitHub,2023.

[6] Q.Wu,G.Bansal,J.Zhangetal.,"AutoGen:EnablingNext-Gen LLM Applications via Multi-Agent Conversation," arXiv preprintarXiv:2308.08155,2023.

[7] Google DeepMind, "Gemini: A Family of Highly Capable MultimodalModels,"arXiv:2312.11805,2023.

[8] Anthropic, "Model Context Protocol Specification," 2024. [Online].Available:https://modelcontextprotocol.io

[9] M. Chen et al., "Evaluating Large Language Models Trained onCode,"arXiv:2107.03374,2021.

[10] C. E. Jimenez et al., "SWE-bench: Can Language Models Resolve Real-World GitHub Issues?" arXiv:2310.06770, 2023.