diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..9144501c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,170 @@
+# AGENTS.md - Agent Guidelines for PIP
+
+This file provides guidance for agentic coding agents working on the PIP (Platform Independent Primitives) codebase.
+
+## Project Overview
+
+PIP is a C++ cross-platform library providing platform-independent abstractions for:
+- Core/Types: Strings, variants, containers, datetime, networks
+- Threading: Mutexes, semaphores, thread pools, timers
+- I/O: Files, serial, CAN, GPIO, SPI, Ethernet
+- Math: Vectors, matrices, FFT, quaternions
+- Crypto: MD5, SHA, BLAKE2, SipHash
+- Compression: zlib support
+- HTTP: Client and server support
+- Serialization: JSON, binary, XML
+
+## Build Commands
+
+### Basic Build
+```bash
+cmake -B ../build_pip
+cmake --build ../build_pip
+```
+
+### Build with Tests
+```bash
+cmake -B ../build_pip -DTESTS=ON
+cmake --build ../build_pip
+```
+
+### Run Tests
+```bash
+ctest --test-dir ../build_pip/tests/                 # Run all tests
+ctest --test-dir ../build_pip/tests/ -R <regex>      # Run specific tests matching regex
+ctest --test-dir ../build_pip/tests/ -V              # Verbose output
+```
+
+To run a single test:
+```bash
+# Build the test executable, then run directly:
+../build_pip/tests/pip_<test_name>_test
+# Or use ctest with specific test name
+ctest --test-dir ../build_pip/tests/ -R "TestName"
+```
+
+### Other Commands
+```bash
+cmake --build ../build_pip --target clean    # Clean build
+cmake --install ../build_pip                 # Install
+cmake --build ../build_pip --target doc      # Build documentation
+```
+
+### Build Options
+```bash
+-DTESTS=ON           # Build tests
+-DCOVERAGE=ON        # Build with coverage
+-DICU=ON             # ICU support for codepage conversion
+-DSTD_IOSTREAM=ON    # std::iostream operators support
+-DINTROSPECTION=ON   # Build with introspection
+-DPIP_BUILD_CRYPT=ON # Crypt module (requires libsodium)
+-DPIP_BUILD_FFTW=ON  # FFT support
+```
+
+## Code Style Guidelines
+
+### File Organization
+- Header files: `libs/main/**/*.h`
+- Source files: `libs/main/**/*.cpp`
+- Private headers: `*_p.h`
+- Tests: `tests/<module>/`
+- Use Doxygen comments (`/*! ... */`) for documentation with `\brief`, `\param`, `\return`
+
+### Naming Conventions
+- **Classes**: PascalCase with `PI` prefix (e.g., `PIString`, `PIByteArray`, `PIVariant`)
+- **Functions**: camelCase (e.g., `toAscii()`, `isEmpty()`, `append()`)
+- **Member variables**: snake_case, or just lowercase (e.g., `array_size`, `count`)
+- **Constants**: PascalCase or UPPER_SNAKE_CASE
+- **Enums**: PascalCase for enum names and values
+
+### Code Formatting
+- **Indentation**: Use tabs (4 spaces equivalent) or spaces - match existing code
+- **Braces**: Opening brace on same line for functions, new line for namespaces/classes
+- **Includes**: System includes first, then project headers
+- **Use forward declarations** where possible to reduce compile times
+- **Use `nullptr`** instead of `NULL`
+
+### C++ Standards
+- C++11 standard (enforced in CMakeLists.txt)
+- Use `override` keyword for virtual function overrides
+- Use `explicit` for single-argument constructors
+- Use `const` member functions where applicable
+- Use range-based `for` loops when possible
+
+### Error Handling
+- Return error codes
+- DO NOT USE exceptions
+- Use `piCerr` and `piCout` for error messages
+- Check for null pointers where appropriate
+
+### Module Structure
+
+Each module typically has:
+1. Public header: `pip_<module>.h` or `<classname>.h`
+2. Private implementation: `<classname>.cpp` or `<classname>_p.cpp`
+3. Use `PIP_EXPORT` macro for symbols that need to be exported from the library
+
+Example class structure:
+```cpp
+// header.h
+#ifndef MODULE_CLASSNAME_H
+#define MODULE_CLASSNAME_H
+
+#include "pip_export.h"
+
+class PIP_EXPORT ClassName {
+public:
+    ClassName();
+    ~ClassName();
+
+    void doSomething();
+    bool isValid() const;
+
+private:
+    void privateMethod();
+    int data;
+};
+
+#endif // MODULE_CLASSNAME_H
+
+// source.cpp
+#include "header.h"
+#include "piincludes_p.h"
+
+ClassName::ClassName() : data(0) {}
+```
+
+### Testing
+- Use Google Test framework
+- Test files go in `tests/<module>/`
+- Use `TEST(TestSuite, TestName)` or `TEST_F(TestFixture, TestName)` for test cases
+- Use `ASSERT_*` for fatal failures, `EXPECT_*` for non-fatal
+- Test naming: `<ClassName>_<TestDescription>`
+
+Example:
+```cpp
+#include "pistring.h"
+#include "gtest/gtest.h"
+
+TEST(PIString_Tests, constructor_empty) {
+    PIString str;
+    ASSERT_TRUE(str.isEmpty());
+}
+```
+
+### Module Dependencies
+- Main library: `libs/main/`
+- Third-party: `3rd/`
+- Utils: `utils/`
+
+### Important Macros
+- `PIP_EXPORT` - Export symbol from shared library
+- `PIP_NO_EXPORT` - Don't export
+- `PIP_DEPRECATED` - Mark as deprecated
+- Conditional compilation: `#ifdef PIP_ICU`, `#ifdef WINDOWS`, etc.
+
+### Key Files
+- `CMakeLists.txt` - Main build configuration
+- `libs/main/pip.h` - Master include
+- `libs/main/piplatform.h` - Platform definitions
+- `tests/CMakeLists.txt` - Test configuration