DarkPs Agent
Enterprise-Grade, Local-First Agent Framework
An extensible automation framework engineered for project workspaces, developer tooling, model orchestration, MCP integration, and reusable runtime capabilities.
Designed for open-source distribution — architected for production-grade automation and code operations.
Soft, reliable, and flexible by design. DarkPs Agent is developed to provide a refined experience across desktop computers, laptops, and other supported devices.
▸ Executive Summary
DarkPs Agent provides autonomous workspace comprehension, self-registering tool discovery, and unified access to both cloud-based and local model backends — enabling extension without modification of core infrastructure.
| Capability | Description |
|---|---|
| Workspace Intelligence | Automatically interprets current project structure |
| Tool Auto-Discovery | Loads and executes tools registered in interpreter/ |
| Unified Model Access | Integrates providers from api/; native support for local GGUF models |
| Contextual Instructions | Ingests project directives directly from workspace files |
| MCP Integration | Extends functionality through connected MCP servers |
| Persistent Memory | Maintains project context and developer notes across sessions |
| Branded Runtime | Renders a custom identity layer and startup signature on launch |
| Cross-Device Design | Developed with compatibility and usability across all supported devices in mind |
▸ Core Capabilities
DarkPs Agent is provisioned with the following operational capabilities out of the box:
- File Operations — reading, writing, editing, and structural inspection
- Code Intelligence — in-workspace code analysis and search
- Web Access — search and content inspection
- Platform Integration — GitHub and Hugging Face support
- Transfer Utilities — upload and download helpers
- Execution Layer — command execution helpers
- Language Processing — local language detection and context resolution
- Session Persistence — project and session memory support
- MCP Execution — full MCP tool invocation support
- Multi-Device Support — designed for a consistent experience across supported devices
Note: Additional capabilities can be integrated without modifying the agent core.
▸ Cross-Platform Support
DarkPs Agent is developed to be usable across all supported devices, with a clean and adaptable workflow for different screen sizes and working environments.
| Environment | Experience |
|---|---|
| Desktop | Full workspace control and development workflow |
| Laptop | Portable project management and coding experience |
| Supported Devices | Flexible operation wherever the runtime environment is available |
Developed by Dark — with a focus on portability, smooth operation, and a refined user experience across devices.
▸ Architecture
The repository is structured for automatic discovery of new modules:
DarkPs-Agent/
├── api/ → Service providers (cloud / API-backed models)
├── interpreter/ → Developer tools and workspace actions
├── core/ → Model selection, environment checks, startup logic
├── Projects/ → Default working directory for user projects
└── MCP/ → MCP server configuration and documentation
| Directory | Responsibility |
|---|---|
api/ |
Houses all service provider integrations |
interpreter/ |
Houses all developer tools and workspace-level actions |
core/ |
Governs model selection, environment validation, and startup sequencing |
Projects/ |
Default working area for user-managed projects |
MCP/ |
Central location for MCP server configuration and reference notes |
▸ Extending the Framework
Registering a New Service — api/
- Create a new Python module within
api/. - Expose a single, well-defined callable entry point for the service.
- Scope the service to one provider or API only.
- Register the model identifier in
model.pyto make it selectable by the agent. - Preserve streaming compatibility where the provider supports it.
Design Principle: Introduce a provider module, register the model mapping, and the agent handles the rest.
Registering a New Tool — interpreter/
- Create a new Python module within
interpreter/. - Expose the tool as a callable function or a lightweight tool class.
- Scope the tool to a single, well-defined task.
- Maintain predictable, clearly-typed input and output behavior.
- Save the module — the runtime discovers it automatically at startup.
Typical categories: file operations, code inspection, web utilities, repository operations, transfer helpers, and command-oriented utilities.
▸ Model Management
All model definitions — both cloud-based and local — are centrally managed in model.py.
| Service Models | Local Models |
|---|---|
| Cloud or API-backed models. Each registered entry may define: • Model identifier • Backend source • Optional agent-facing configuration hints |
Local GGUF-format models for fully offline operation: • Maintained as a discrete, versioned list • Selectable directly from the agent menu |
▸ Startup Sequence
On launch, the agent executes the following sequence:
| Step | Action |
|---|---|
| 1 | Renders the custom startup signature from логотип.md |
| 2 | Applies identity configuration from identity.md |
| 3 | Inspects the active workspace |
| 4 | Loads all registered runtime tools and services |
| 5 | Prompts for local or online model selection |
| 6 | Initializes the selected project directory |
Startup Signature Rendering Speed
Governed by the скорость parameter in main.py.
Lower values increase rendering speed · Higher values decrease rendering speed
Data Cleanup Policy
Governed by the database parameter in main.py:
| Value | Behavior |
|---|---|
True |
Enables default startup cleanup routines |
False |
Disables startup cleanup routines |
This setting determines whether stored data artifacts persist or are cleared at startup.
▸ Workspace Selection
At startup, the operator may specify a project directory manually.
| Input | Result |
|---|---|
| Enter (no input) | Defaults to the standard Projects/ workspace |
| Custom path | Initializes the specified project directory |
This preserves rapid startup for routine use while retaining full configurability for custom deployments.
▸ Project Instructions
The repository relies on project-side instruction files to accelerate workspace comprehension.
Governing Convention:
| File | Purpose |
|---|---|
Projects/USER_MESSAGE |
Primary user-facing directive |
MCP/важный |
Mandatory reference note for MCP usage |
identity.md |
Agent personality and behavioral profile |
▸ MCP Integration
MCP servers are supported through the MCP/ directory.
Governing Convention:
- Maintain all MCP configuration within
MCP/ - Ensure the note within
MCP/важныйis reviewed prior to deployment - Keep MCP server documentation accurate and current
▸ Startup Signature Customization
The startup signature is governed by логотип.md.
Replacement Procedure:
- Open
логотип.md - Insert the desired brand mark or signature
- Preserve terminal-readable formatting
- Save the file
- Restart the agent
The updated signature will render on the next launch.
▸ Identity Configuration
identity.md governs the public-facing identity of the agent, including:
- Agent designation
- Personality profile
- Communication tone
- Operational working style
- Brand voice
This is the designated configuration surface for presentation behavior — no core code modification required.
▸ Apache License 2.0
This project is released under the Apache License 2.0.
The Apache License 2.0 permits use, modification, distribution, and contribution under its terms. See the full license text in the project repository.
Documentation is maintained with a focus on user-facing behavior, setup procedures, and extension points — ensuring new contributors can onboard efficiently.
Run:
python3 main.py
